From de4820b595742db0d5836c8c14f5d8375556dce2 Mon Sep 17 00:00:00 2001 From: zizi Date: Thu, 10 Sep 2026 19:39:59 +0800 Subject: [PATCH] =?UTF-8?q?=E6=89=B9=E6=AC=A1=E7=B4=A2=E5=BC=95=E4=B8=8E?= =?UTF-8?q?=E5=85=A5=E5=8F=A3=E6=94=B6=E5=8F=A3=EF=BC=9A=E7=9B=AE=E5=BD=95?= =?UTF-8?q?=E7=B4=A2=E5=BC=95=E7=99=BB=E8=AE=B0=E3=80=81=E5=B7=A5=E7=A8=8B?= =?UTF-8?q?=E5=85=A5=E5=8F=A3=E8=AF=B4=E6=98=8E=E4=B8=8E=E6=97=A7=E5=B7=A5?= =?UTF-8?q?=E4=BD=9C=E5=8F=B0=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit .agent 与 docs 各级目录.md 登记批次新增的规则、约束、规范与技能；AGENTS.md/README.md 含开工时保留的原仓修改与批次新增的工程入口说明（混合改动，按用户指示整文件收口）；web/app.py 旧本地人审工作台入口调整。 --- .agent/rules/目录.md | 7 ++ .agent/skills/目录.md | 1 + .agent/目录.md | 11 +-- .agent/约束/目录.md | 3 + .agent/规范/目录.md | 2 + AGENTS.md | 28 ++++--- README.md | 190 ++++++++++++++++++++++++++++++------------ docs/功能规格/目录.md | 1 + docs/目录.md | 6 +- web/app.py | 1 - 10 files changed, 178 insertions(+), 72 deletions(-) diff --git a/.agent/rules/目录.md b/.agent/rules/目录.md index 45072fb..2b588d7 100644 --- a/.agent/rules/目录.md +++ b/.agent/rules/目录.md @@ -1,3 +1,10 @@ | 名称 | 相对地址 | 内容描述 | 使用场景 | 使用要求 | |------|----------|----------|----------|----------| | 研发执行流程 | [执行流程.md](执行流程.md) | 动态研发时序六阶段流程、阶段门和完成条件 | 任务启动、阶段切换、验证与经验沉淀时 | 按判定条件单向流转，不得跳过验证或用户确认 | +| 模块依赖 | [模块依赖.md](模块依赖.md) | 公共接口、共享零反向依赖、技能无实现、接入不写表等依赖方向硬规则 | 新建模块、跨模块调用、写接入层或技能前 | 与 tests/架构/test_模块依赖.py 联动；违反先修方向再继续 | +| 测试隔离 | [测试隔离.md](测试隔离.md) | 默认离线、外部环境显式标记、用例身份后缀、空收集不通过的测试硬规则 | 编写或运行任何测试、配置 CI 与验证环境时 | 与 tests/conftest.py 和 make 检查联动；替身必须显式标记 | +| 正式变更 | [正式变更.md](正式变更.md) | 唯一写入口、作者确认前置、原子幂等与失败可见的提交硬规则 | 实现或评审任何正式内容写入路径时 | 与 S01 合同联动；禁止第二条写路径 | +| 任务与证据 | [任务与证据.md](任务与证据.md) | 持久化记账、冻结输入、租约、两种用途、未知调用对账与原文保护 | 实现或评审任务运行、模型调用与证据留存时 | 与 S02 合同和任务工具事件合同联动 | +| 元数据消费 | [元数据消费.md](元数据消费.md) | 模具归元数据、实例归业务、只增不改、投影按用途的硬规则 | 实现或评审结构定义、扩展与投影时 | 与 S04 合同联动；未知字段不静默丢弃 | +| 审校与修订 | [审校与修订.md](审校与修订.md) | 选区语义、不擅动正文形态、受控修订与派生失败可见 | 实现或评审修订、选段与章后处理时 | 与 B06 和正文结构合同联动 | +| 文档与资源生成 | [文档与资源生成.md](文档与资源生成.md) | 生成物只由登记输入产生、索引一致、资源带发布身份 | 修改目录索引、登记资源或声明命令时 | 与 工具/维护索引.py 和 工具/构建资源包.py 联动 | diff --git a/.agent/skills/目录.md b/.agent/skills/目录.md index c542012..5e4f86a 100644 --- a/.agent/skills/目录.md +++ b/.agent/skills/目录.md @@ -3,4 +3,5 @@ | 规划类技能 | [目录.md](规划/目录.md) | 概念破题、故事骨架、伏笔铺垫与叙事动力等故事规划方法 | 故事构思、搭建节拍表、设计高潮与收尾时 | 产出结构骨架与因果链，不代写正文 | | 写作类技能 | [目录.md](写作/目录.md) | 人物设计、人物登场、对白暗劲、视角选择与场景执行等写作方法 | 正文生成、场景加厚、对白打磨与修辞校准时 | 坚持具体压倒抽象、无心理描写法与白描 | | 诊断类技能 | [目录.md](诊断/目录.md) | 小说全篇体检、结构断裂诊断与质量短板扫描 | 稿件完成、初审体检、分析弃读与拒稿根因时 | 给出客观证据引文，定位具体改进技能 | +| 操作类技能 | [目录.md](操作/目录.md) | 新版结构维护、任务查询、私人探索及正文候选审阅 | 使用新版具名操作时 | 不扩大用户授权或替代业务确认 | diff --git a/.agent/目录.md b/.agent/目录.md index 3b6797d..fd0b151 100644 --- a/.agent/目录.md +++ b/.agent/目录.md @@ -1,9 +1,10 @@ | 名称 | 相对地址 | 内容描述 | 使用场景 | 使用要求 | |------|----------|----------|----------|----------| -| 规则 | rules/目录.md | 动态研发流程与团队长期执行规则 | 任务启动、阶段流转、门禁检查与经验沉淀前 | 先读目录，再按任务打开具体规则 | -| 约束 | 约束/目录.md | 数据、权限、模型与代码的不可逾越边界 | 涉及数据读写、模型调用、探索边界与代码提交时 | 先读目录；违反红线一票否决 | -| 规范 | 规范/目录.md | 提示词与技能审查标准、术语规范、指令集规范与去 AI 味道工程规范 | 编写指令、起名、设计提示词、技能审查、写文档与代码审查时 | 全仓必须统一使用纯中文单名与中立指令语法，审查按标准逐条核验 | -| 作者 | 作者/目录.md | 作者自然语言路由、六个创作场景与原生中文写作共同合同 | 作者提出定故事、排故事、塑人物、续写、修改或诊断请求时 | 先读路由指令，再只打开命中的场景；生成或修改正文时同时读取共同写作合同 | +| 规则 | rules/目录.md | 执行流程与模块依赖、测试隔离、正式变更、任务与证据、元数据消费、审校修订、文档与资源生成等长期硬规则 | 任务启动、阶段流转、门禁检查与经验沉淀前 | 先读目录，再按任务打开具体规则 | +| 约束 | 约束/目录.md | 红线、作者主权、数据与读取范围、凭据与外部调用等不可逾越边界 | 涉及数据读写、模型调用、探索边界与代码提交时 | 先读目录；违反红线一票否决 | +| 规范 | 规范/目录.md | 审查标准、术语、指令集、命名、中文正文与界面、去 AI 味道等规范 | 编写指令、起名、设计提示词、技能审查、写文档与代码审查时 | 全仓统一中文单名与中立指令语法，审查按标准逐条核验 | +| 作者 | 作者/目录.md | 作者自然语言路由、提示词驱动的作品探索、六个创作场景与中文写作合同 | 作者提出定故事、排故事、塑人物、续写、修改或诊断请求时 | 先读路由指令，再只打开命中的场景；生成或修改正文时同时读取共同写作合同 | | 技能 | skills/目录.md | 本仓长期复用的方法技能目录与能力入口 | 命中特定创作方法场景时 | 按目录渐进读取对应中文单名下的 `SKILL.md` | -| 智能体 | agents/目录.md | 五个角色提示词与中心角色合同入口 | 派发角色任务与构建提示词时 | 先读中心角色合同，再读取具体角色文件 | +| 新版角色 | 角色/目录.md | 新版五类角色的稳定职责资源 | 新版发布资源与任务装配 | 模型和工具策略另由配置固定；当前实施状态见工作包证据 | +| 旧版智能体 | agents/目录.md | 旧实现仍使用的五个角色提示词 | 旧运行环境与迁移核对 | 不作为新版安装包的资源发现入口，完整退出按切换计划 | diff --git a/.agent/约束/目录.md b/.agent/约束/目录.md index b34c0d7..08e39fe 100644 --- a/.agent/约束/目录.md +++ b/.agent/约束/目录.md @@ -1,3 +1,6 @@ | 名称 | 相对地址 | 内容描述 | 使用场景 | 使用要求 | |------|----------|----------|----------|----------| | 红线约束 | [红线约束.md](红线约束.md) | 数据权威、探索边界、模型治理与代码提交红线 | 涉及数据库、模型、外部探索或提交操作前 | 任何一项命中即停止，不得以便利或进度为由绕过 | +| 作者主权 | [作者主权.md](作者主权.md) | 先审后入、作者身份不可伪造、决策可追溯与私人探索边界 | 实现或评审任何作者决策与确认链路时 | 候选必须经作者明确确认；模型无作者身份 | +| 数据与读取范围 | [数据与读取范围.md](数据与读取范围.md) | 正式权威、无默认回退、旧库冻结、来源范围冻结与评测隔离 | 连接数据库、读取资料、配置用途或触碰旧数据时 | 缺配置即失败；旧正式库对新技术只读 | +| 凭据与外部调用 | [凭据与外部调用.md](凭据与外部调用.md) | 凭据值不入库不入文、受控读取、生产与测试配置分离 | 涉及凭据、模型调用、外部网络与留证时 | 只记获取位置；持久化前脱敏 | diff --git a/.agent/规范/目录.md b/.agent/规范/目录.md index 223468e..765b935 100644 --- a/.agent/规范/目录.md +++ b/.agent/规范/目录.md @@ -3,4 +3,6 @@ | 提示词与技能审查标准 | [审查标准.md](审查标准.md) | 智能体提示词四问、技能质量八问、中文身份与审查产出合同 | 新增、修改或复核提示词与技能时 | 先跑机械门，再按严重度完成人工审查 | | 指令集规范 | [指令集规范.md](指令集规范.md) | 跨宿主中立语法、中文单名引用与决策阶梯 | 编写团队智能体指令和执行文档时 | 禁止宿主私有命令、私有参数和本机绝对路径 | | 术语规范 | [术语规范.md](术语规范.md) | 全仓中文术语、标准单名和禁用混杂词 | 起名、改术语或审查业务表达时 | 一个概念只保留一个正式中文名称 | +| 命名 | [命名.md](命名.md) | 中文优先、展示名与稳定身份分离、模块三件套与测试符号约定 | 新建文件、模块、测试或工具时 | 技术约定名保留英文；身份不为改名破坏 | +| 中文正文与界面 | [中文正文与界面.md](中文正文与界面.md) | UTF-8 与码点、不规范化、输入法组合期不提交、界面中文 | 处理正文文本、编辑器行为或界面文案时 | 位置按码点左闭右开；规范化必须显式 | | 去 AI 味道工程规范 | [去AI味道工程规范.md](去AI味道工程规范.md) | 文档、指令与代码中的空话、模板腔和机械表达治理 | 编写或审阅人读文档、提示词和代码时 | 直陈事实、动作与后果，删除无业务作用的套话 | diff --git a/AGENTS.md b/AGENTS.md index 15c1a49..19e63e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,17 +22,24 @@ ```text agent-example/ ├── .git/ # 独立 Git 仓元数据 -├── framework/ # FrameworkPort 通用协议与宿主适配器（Pi / DSH 对照） -├── runtime/ # 宿主无关执行底座（agent_executor / runs） -├── web/ # 本地人审工作台（只读 data/muse.db + 三个受控写端点） +├── src/muse/ # 新版模块化单体（装配、共享基础；业务模块随改造包落地） +├── tests/ # 新版测试（单元/契约/集成/架构 + 夹具；旧测试树由旧环境运行） +├── 工具/ # 工程生成与检查入口（资源打包、接口生成、索引检查） +├── 配置/ # 无凭据配置模板 +├── web/ # 前端：新版 React/TS 工作台（随包建设）+ 旧本地人审工作台 app.py +├── 数据库/ # 新版迁移与旧库迁移资料（随 W03 起） +├── framework/ # 旧：FrameworkPort 通用协议与宿主适配器（Pi / DSH 对照） +├── runtime/ # 旧：宿主无关执行底座（agent_executor / runs） ├── .agent/ # 智能体能力中枢（作者入口、角色提示词、方法技能、规则、约束与规范） -├── muse/ # Muse 业务核心（SoT、内容本体、创作生命周期、权威数据与平台共享库） -├── tests/ # 技能实现测试、架构门禁与回归验证 -├── docs/ # 单次任务探索、计划、评测资料、样张与历史执行记录 -├── .venv/ # 本地 Python 运行环境 -├── requirements.txt # Python 依赖清单 +├── muse/ # 旧：Muse 业务实现（验收后逐步退出） +├── docs/ # 设计 SSOT、单次任务探索、计划、评测资料与历史执行记录 +├── .venv/ # 新版仓内解释器（uv 管理） +├── .venv-旧/ # 旧代码运行环境（requirements.txt 可重建） +├── requirements.txt # 旧实现 Python 依赖清单 +├── pyproject.toml # 新版应用包、命令、依赖与检查配置 +├── Makefile # 新版安装、生成、检查、测试与构建入口 ├── CLAUDE.md # Claude Code 兼容入口，只引用 AGENTS.md -└── README.md # 历史概览，不是当前运行态 SoT +└── README.md # 安装、启动与日常使用入口 ``` --- @@ -44,6 +51,7 @@ SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面 | 类别 | 载体 / 路径 | 权威职责 | |---|---|---| | 总体设计 | [`../design-docs/`](../design-docs) | Muse 的概念、产品、业务和总体架构 SoT（设计 SSOT）。 | +| 新版重写目标 | [docs/系统架构/新版设计/目录.md](docs/系统架构/新版设计/目录.md) | 新版主体完整目标设计、元数据、文件职责及研究依据；不据此宣称现有实现已完成。 | | 领域 SoT | [`muse/sot/domains/`](muse/sot/domains/_index.md) | 本仓各业务领域边界、数据权威、落库合同与领域协作 SoT（01-08 域）。 | | 边界合同 | [`muse/sot/边界合同.md`](muse/sot/边界合同.md) | 组件职责边界与约束归属唯一事实源：智能体/技能/工具 server/主代理职责划分。 | | 角色合同 | [`muse/sot/角色合同.md`](muse/sot/角色合同.md) | 5 个角色（写手/规划/抽取/检测/裁判）的稳定输入边界、模型策略、工具权限与派发合同。 | @@ -62,7 +70,7 @@ SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面 ## 4. 工作协议（硬约束） 1. **读后动手与渐进发现**：复杂任务开工前必须先读 SoT、角色合同与技能索引；技能发现遵循 `AGENTS.md → 索引 → SKILL.md` 渐进展开，不依赖宿主私有文件投影或猜测。 -2. **机械验证优先与完成=验证**：遵循父仓反假绿规则，Python 统一使用仓内解释器 `.venv/bin/python`；必须通过相关单元测试、门禁与 `git diff --check`，无自动化证据严禁声称“完成/修复/通过”。 +2. **机械验证优先与完成=验证**：遵循父仓反假绿规则，新版工程统一使用仓内解释器 `.venv`（uv 管理；旧代码用 `.venv-旧`）；日常入口 `make 检查`（格式+类型+索引）、`make 测试`（默认离线进程隔离）、`make 数据库测试`（需 `MUSE_TEST_DATABASE_URL`）；必须通过相关单元测试、门禁与 `git diff --check`，无自动化证据严禁声称“完成/修复/通过”。 3. **数据权威与先审后入**：数据库为唯一正式权威，严禁裸连操作；正文、规划与知识抽取默认生成 Shadow 候选，经用户明确确认后方可写入 Canonical 正典事实。 4. **模型治理与受控探索**：模型调用严格遵守 5 小时额度窗口与受控治理链，角色严格锁定合同指定模型（写手/规划/裁判固定顶级推理模型）；确定性逻辑、门禁与报告组装由脚本完成，严禁调用模型；智能体探索仅限圈定只读工具并留痕。 5. **会话交互与汇报纪律**：全程使用简体中文白话，坚决去除 AI 味（直陈事实、动作与后果，禁止清嗓子套话与空转缓冲词）；需要用户决策时，必须交代清楚前因后果及各选项对下游的影响。 diff --git a/README.md b/README.md index 511cc4e..6bd173f 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,157 @@ -# agent-example +# agent-example（Muse 单用户版） -`agent-example` 的目标是成为 Muse 的单用户缩小版，以 PostgreSQL 为正式内容权威：ReAct Agent 通过角色 Agent、Skill 和确定性工具，完成长篇小说的作品管理、实体维护、范式复用、规划、写作、审核、用户决策和经验复利。代码与文档在 Git，正式内容在数据库。 +Muse 的单用户缩小版：AI 驱动的长篇创作工具。**正在按新版设计改造**（见 [`docs/系统架构/新版设计/阅读指南.md`](docs/系统架构/新版设计/阅读指南.md) 与 [改造计划](docs/系统架构/新版设计/改造计划/总计划.md)），新版工程骨架已落地，业务能力按工作包逐步交付。 -本项目不包含管理员、多用户、租户、市场、计费和资产交易。完整 Muse 产品、业务和总体架构仍以父仓 [`../design-docs/`](../design-docs) 为准。 +正式内容权威是 PostgreSQL；Git 是代码、技能、文档与 DDL 的权威。本项目不含管理员、多用户、租户、市场、计费与资产交易。 -## 数据权威 +## 新版工程入口（当前） -核心合同是： +```bash +# 安装（uv 管理 .venv 为新版仓内解释器） +make 安装 +make 前端安装 # 使用 web/pnpm-lock.yaml；生成和索引核对需要 Node/TypeScript -```text -PostgreSQL（muse-example 库） = 正式内容权威（作品 / 章 / 正文 / 实体 / 范式 / 用户决策 / 运行回执 / raw） -Git = 代码 / Skill / 文档 / DDL 的权威，并可对作品信息与作品文本留痕（历史 / 备份） -库内向量索引 = 数据库一侧的检索加速，可从库重建 +# 日常检查：格式 + 类型 + 索引一致性 +make 检查 +make 前端检查 +make 前端测试 + +# 离线测试（默认 OS 进程隔离，未标记外部环境的用例禁止联网连库） +make 测试 +make 测试 用例=TC-a5c7d4adafe3 # 按稳定用例 ID 选择单例 + +# 隔离数据库测试（需先导出 MUSE_TEST_DATABASE_URL，缺变量直接失败） +make 数据库测试 + +# 实际Pi SDK整链：另需MUSE_PI_NODE与MUSE_PI_PACKAGE，固定Pi 0.84.4、Node至少22.19.0 +# 这些是本地运行路径；提供方使用合成HTTP，不调用外部模型 +make 宿主测试 + +# 生成（资源包 / 接口合同 / 索引）与构建发布包 +make 生成 +make 构建 ``` -正式内容以库为准；Git 留痕不是权威，只读看板只读库，两者冲突时以库为准。可恢复性靠数据库备份，加上 Git 里的代码与 DDL 重建库结构。一切输入和产出都必须落库才能被看板看见。 +- 新版源码：`src/muse/`（模块化单体，中文模块名；公共接口在各模块 `接口.py`）。 +- 新版测试：`tests/单元|契约|集成|架构/`，用例以完整 `case_id` 绑定实际文件、符号与参数行；六位后缀只辅助阅读。 +- 工程工具：`工具/`（资源打包、接口生成、索引检查），登记输入在 `工具/资源登记.json` 与 `工具/生成输入.json`。 +- 前端工作台（React/TS）：`web/`，随 W07 起接入真实后端。 -## 三条正交轴 +## 作者工作台与结构入口 -```text -内容：作品 + 实体 + 范式 -流程：上下文组装 -> 创作 -> 质量审核 -> 用户决策 -> 复利 -能力：Agent + Skill + Tool + 数据库存储 + 只读看板 +运行配置草案使用[提供方模板](配置/提供方.example.toml)，经CLI保存到所选用途的数据库： + +```bash +.venv/bin/python -m muse 配置 <私人应用配置.toml> 保存 <配置ID> <版本> --内容 <运行配置草案.toml> +.venv/bin/python -m muse 配置 <私人应用配置.toml> 查看 <配置ID> <版本> ``` -领域边界、数据权威和验收合同见 [`muse/sot/domains/_index.md`](muse/sot/domains/_index.md)。框架执行端口见 [`framework/README.md`](framework/README.md)。该目录定义目标行为，不代表所有落库写入和只读看板已经完成实现。 +保存与查看不会自动启用。任务执行从已验证启用并绑定的版本装配；生产能力验证器和对应的作者启用流程仍在实施，不能用离线配置检查替代。 -## 当前工程入口 +复制 `配置/应用.example.toml` 到私人配置目录，将数据库连接和工作台口令分别保存在该目录的受控文件中。相对凭据地址以配置文件所在目录为起点。 + +先运行`.venv/bin/python 工具/环境预检.py`取得当前`resource_build_id`，填入私人配置的资源发布身份。执行任务固定这一构建；换装资源后已有任务不能静默改用新版。 + +```bash +# 发布包内工作台；公开地址和写入来源必须与浏览器实际访问地址一致 +.venv/bin/python -m muse 服务 <私人作者配置.toml> + +# 维护配置发布固定种子；重复发布幂等，不启用任何实例绑定 +.venv/bin/python -m muse 结构 <私人维护配置.toml> 发布内置 +.venv/bin/python -m muse 结构 <私人作者配置.toml> 查看 character --版本 1 +.venv/bin/python -m muse 结构 <私人作者配置.toml> 维护 <结构请求.json> + +.venv/bin/python -m muse 任务 <私人作者配置.toml> 列表 +.venv/bin/python -m muse 任务 <私人作者配置.toml> 查看 <任务ID> +.venv/bin/python -m muse 任务 <私人作者配置.toml> 控制 <控制请求.json> +``` + +任务控制 JSON 使用 `command_id`、`target_ref`、`expected_state`、`action`，其中 action 为“暂停”“取消”或“恢复”。重试同一请求保留 command_id；恢复由服务端登记的流程检查来源、结构、授权与预算，缺少对应业务处理器时明确拒绝。 + +当前工作台可新建作品、编辑动态档案、添加章节并手写正文。正文自动保存保留版本；冲突时先比较服务器稿件，回退会生成新版本。未提交的正文缓冲留在当前浏览器，重开时先与服务器基线比较。候选审阅、引用选择与作品结构升级仍在实施，不能将人工主链通过视为完整创作链完成。 + +人工命令与网页复用同一业务入口： + +```bash +.venv/bin/python -m muse 作品 <私人作者配置.toml> 结构 <作品ID> --结构 work_core --版本 1 +.venv/bin/python -m muse 作品 <私人作者配置.toml> 保存档案 <档案请求.json> +.venv/bin/python -m muse 作品 <私人作者配置.toml> 新增章节 <章节请求.json> +.venv/bin/python -m muse 作品 <私人作者配置.toml> 保存正文 <正文请求.json> +.venv/bin/python -m muse 作品 <私人作者配置.toml> 正文 <章节ID> +.venv/bin/python -m muse 作品 <私人作者配置.toml> 回退正文 <回退请求.json> +``` + +请求外壳由 [`创作操作.py`](src/muse/接入/创作操作.py) 与[生成合同](docs/接口契约/生成/openapi.generated.json) 定义。作者身份取自配置或会话；正文草稿使用[受限文档树](docs/系统架构/新版设计/接口契约/正文结构与中文选区.md)，不提交编辑器HTML。 + +## 新库配置与迁移 + +清理当前配置的无租约暂存与读取回执： + +```bash +.venv/bin/python -m muse 管理 <私人应用配置.toml> 清理无租约暂存 +.venv/bin/python -m muse 管理 <私人应用配置.toml> 查看清理回执 <对象ID> +``` + +该操作保留已登记租约、未知资料和其他命名空间。旧的非空未标记目录须先按迁移合同承接，不能直接交给新版清理器。 + +按 `配置/应用.example.toml` 配置连接引用和用途。三类角色由管理员使用 `数据库/初始化/用途角色.sql` 显式创建，独立目标库交由 `muse_maint` 所有；应用迁移不创建角色。`muse_app` 处理业务对象，`muse_eval` 处理评测对象，生产角色不能读取 oracle。 + +`make 生成` 将迁移投影到包内；`make 迁移 配置=<私人维护配置路径>` 通过 maintenance 装配执行。缺凭据不会回退默认库。 + +## 过渡期旧实现 + +旧实现位于原工作树的 `muse/`、`framework/`、`runtime/`、`web/app.py`。新版在隔离工作树使用自己的 `.venv`；原工作树的旧 harness 仍沿原 `.venv` 路径启动，须保持该路径连接旧依赖环境。旧环境可依据 `requirements.txt` 重建： + +```bash +uv pip install --python .venv/bin/python -r requirements.txt +``` + +旧正式库（mini-infra `100.64.0.8:5433/muse-example`）与旧 SQLite 账本（`data/muse.db`）对新实现冻结为只读参照；切换按 [切换与回退](docs/系统架构/新版设计/改造计划/切换与回退.md) 执行。旧测试树由旧环境运行，两套收集互不接管。 + +## 目录速览 ```text agent-example/ -├── AGENTS.md # 项目工作入口与规则 -├── CLAUDE.md # 只引用 AGENTS.md 的兼容入口 -├── framework/ # 框架无关执行对象与 Pi 适配器 -├── .agent/ # 角色身份与方法 Skill 挂载源 -│ ├── agents/ # 角色 Agent -│ └── skills/ # 15 个方法 Skill 的嵌套源 -├── muse/ # Muse 业务平面 -│ ├── sot/ # 领域与角色合同 SoT -│ ├── content/ # 作品、实体、范式与结构 schema -│ ├── lifecycle/ # 上下文、流程、质量与 harness -│ ├── authority/ # DB、证据、Studio 与只读工具 -│ └── platform/ # 共享连接、模型、嵌入包 -└── docs/ # 单次任务资料、评测样张和历史执行证据 +├── AGENTS.md # 项目工作入口（唯一事实源） +├── CLAUDE.md # 兼容入口，只引用 AGENTS.md +├── src/muse/ # 新版模块化单体（装配、共享基础、业务模块随包落地） +├── tests/ # 新版测试（单元/契约/集成/架构 + 夹具） +├── 工具/ # 工程生成与检查入口 +├── 配置/ # 无凭据配置模板 +├── web/ # 新版 React/TS 作者工作台（随包建设） +├── 数据库/ # 新版迁移（随 W03 起） +├── muse/ framework/ runtime/ # 旧实现（验收后逐步退出） +├── .agent/ # 智能体能力中枢（规则、约束、规范、技能） +├── docs/ # 设计 SSOT、任务资料与执行证据 +└── data/ # 运行态数据（旧 SQLite 账本与参考原文，gitignore） ``` -正式内容在 PostgreSQL，不在 `content/` 文件目录。判断有没有某个内容，以库里能不能查到为准；不得把库外文件或临时快照说成正式内容。 +## 验证纪律 -## 正向创作 - -```text -用户意图 - -> 读取作品、实体和范式 - -> 冻结角色上下文 - -> 规划/写作 Agent 产生 Shadow 候选 - -> 确定性检查、语义检测和质量审核 - -> 用户原样接受、修改后合并或丢弃 - -> 正式正文（写入库内正文块） - -> 实体草稿、范式观察和复利验证 -``` - -Gate A/B 是开发期离线能力验收，不是正常用户写一章的生产主流程。评测候选固定不可进入 Canonical。 - -## SoT 顺序 - -1. 父仓 `design-docs/`：完整 Muse 产品、业务和总体架构。 -2. 本仓 `muse/sot/domains/`：单用户、数据库为权威的领域边界。 -3. `muse/content/meta/` 与 `muse/lifecycle/flow/chains/`：结构本体和功能链登记。 -4. `.agent/agents/`、`.agent/skills/` 与 `muse/_skills_index.md`：角色、方法与编排能力合同。 -5. `docs/`：单次任务过程、评测资料与执行证据，不覆盖稳定 SoT。 +完成 = 机械验证：无自动化绿证据不得声称完成。测试默认离线禁网禁库；空收集、全跳过、超时与缺依赖都如实呈现，不冒充通过。详见 [`docs/系统架构/新版设计/改造计划/执行与验收.md`](docs/系统架构/新版设计/改造计划/执行与验收.md) 与 [`.agent/rules/测试隔离.md`](.agent/rules/测试隔离.md)。 所有任务从 [`AGENTS.md`](AGENTS.md) 开始。 +## 正文候选 + +章节保存后可进入“比较正文候选”，另拟改稿、编辑候选或按段选择改动。候选保存只增加候选版本；打开审阅后，作者可采纳为正文新版本、拒绝或暂缓。当前人工候选只做格式与版本校验，模型生成与关联事实采纳随相应创作流程接入。 + +CLI 使用 `.venv/bin/python -m muse 审阅 <作者配置> 列表 <章节ID>` 定位；`查看 <候选ID>` 读取候选，`打开 <请求JSON>` 取得固定审阅。`建立候选`、`修改候选` 与 `决定` 的请求合同和执行说明见[决定正文候选去留](.agent/skills/操作/决定正文候选去留/SKILL.md)。 + +## 故事事实接口 + +新版提供 `/api/v1/works/{work_id}/facts/schema` 预览事实结构，`/fact-proposals` 创建提案；通过 `/api/v1/fact-proposals/{proposal_id}/reviews` 打开审阅，再向 `/decisions` 提交作者决定。来源使用确切正文版本及段落引文。提案保存不产生正式事实，确认使用与正文相同的S01事务机制。 + +`/api/v1/works/{work_id}/facts` 按稳定章节身份 `as_of`、事实域确认版本 `system_revision` 和 `view=author|reader|character` 查询；角色视角同时提供 `character_id`。事实、猜测、计划分别返回。作者总览支持后文对早期事件的说明，早期读者查询不会提前得到后文披露。完整世界维护页面随W19接入。 + +## 私人探索稿 + +作者配置中的`文件.探索草稿`指定私人目录。工作台从“先记下一个想法”进入探索页，可保存原话、刷新恢复输入，保存冲突时先比较当前稿。草稿不进入正式作品列表、规划或生成上下文。 + +`.venv/bin/python -m muse 探索 <作者配置> 列表`及`查看 <稿件ID>`读取私人稿；`保存 <请求JSON>`接受draft_id、title、content、expected_hash。新稿expected_hash为null。整理后用`检查 <稿件ID> --预期哈希 `核对最终格式；格式失败非零，方向确认与正式规划仍是独立动作。操作细节见[完善故事基础设定](.agent/skills/操作/完善故事基础设定/SKILL.md)。 + +整理稿通过格式检查后，可以明确选定为某部作品的规划依据。`选定 <请求JSON>`提交command_id和selection（work_id、draft_id、expected_hash、expected_revision）；`查看选定 <作品ID>`读回服务器保存的作者、时间和确切快照。修改私人稿不会改变这份已选来源，正式规划候选仍须单独确认。 +## 人工规划候选 + +`.venv/bin/python -m muse 规划 <作者配置> 结构 <作品ID> --结构 outline --版本 1`读取固定规划结构。`创建候选 <请求JSON>`使用command_id和request；request包含work_id、expected_revision、schema和动态content。候选保存不会产生正式规划。 + +`查看候选`、`打开审阅`和`决定`完成作者明确确认，`查看 <规划ID>`或`列表 <作品ID>`回查正式内容。详见[确认规划候选](.agent/skills/操作/确认规划候选/SKILL.md)。当前这一入口用于人工规划；模型生成、卷与场景节点、近期细化仍在W13实施中。 diff --git a/docs/功能规格/目录.md b/docs/功能规格/目录.md index 0cabbb7..2f8716f 100644 --- a/docs/功能规格/目录.md +++ b/docs/功能规格/目录.md @@ -1,4 +1,5 @@ | 名称 | 相对地址 | 内容描述 | 使用场景 | 使用要求 | |------|----------|----------|----------|----------| | 技能身份中文化与作者创作入口 | 技能身份中文化与作者创作入口.md | 59 个正式技能的中文单名、作者指令层、迁移边界与机械验收合同 | 修改技能名称、发现索引、运行归属或作者创作入口前 | 中文名称、作者交互边界或迁移规则变化时同步更新 | +| 阶段0交互式作品探索 | 阶段0交互式作品探索.md | 一份主文档与六份子阶段提示词、九章产出范式和最终校验的职责边界 | 调整阶段0作者交互、探索指令或最终交付格式时 | 流程只维护在正式 Skill，保留渐进探索与两次人审 | diff --git a/docs/目录.md b/docs/目录.md index 89eb9f2..4f33daf 100644 --- a/docs/目录.md +++ b/docs/目录.md @@ -1,11 +1,11 @@ | 名称 | 相对地址 | 内容描述 | 使用场景 | 使用要求 | |------|----------|----------|----------|----------| -| 系统架构 | 暂无 | 系统怎么切、依赖朝哪、为什么这样切；ADR 在 `决策/` | 跨模块、改边界、选技术底座、写 ADR 时 | 架构或架构决策变化时 | +| 系统架构 | [系统架构/目录.md](系统架构/目录.md) | 系统怎么切、依赖朝哪、为什么这样切；ADR 在 `决策/` | 跨模块、改边界、选技术底座、写 ADR 时 | 架构或架构决策变化时 | | 领域模型 | 暂无 | 业务概念、词什么意思、概念边界；术语全文在 `术语表.md` | 改业务行为、起名、对术语有分歧时 | 新术语或概念边界确认时 | | 数据模型 | 暂无 | 数据长什么样、存在哪、怎么一致 | 改存储、迁移、字段、一致性时 | schema / 数据生命周期变化时 | | 模块设计 | 暂无 | 代码按什么模块分、职责与依赖 | 动模块边界、新代码往哪放拿不准时 | 模块职责或依赖变化时 | -| 功能规格 | 功能规格/目录.md | 功能方案、验收标准与实施执行计划/Runbook（spec） | 实现或评审某功能前 | 功能范围、方案或实施步骤确认时 | -| 接口契约 | 暂无 | 对外/对内接口契约 | 改接口、联调、生成客户端时 | 契约变化时 | +| 功能规格 | 功能规格/目录.md | 功能方案、阶段0提示词探索的设计边界、验收标准与实施计划（spec） | 实现或评审某功能前 | 功能范围、方案或实施步骤确认时 | +| 接口契约 | [接口契约/目录.md](接口契约/目录.md) | 对外/对内接口契约 | 改接口、联调、生成客户端时 | 契约变化时 | | 业务需求 | 暂无 | 要解决谁的什么问题、不做哪些 | 功能还没方案、对齐目标和范围时 | 需求确认或变更时 | | 调用链路 | 暂无 | 一条真实路径经过哪些代码 | 改这条链路、排障、清理相关代码时 | 关键路径稳定或被改写后 | | 模块概要 | 暂无 | 某模块一页纸：干什么、入口在哪 | 第一次接触某模块、给别人指路时 | 模块对外形状变了 | diff --git a/web/app.py b/web/app.py index 4abbe47..b18224a 100644 --- a/web/app.py +++ b/web/app.py @@ -20,7 +20,6 @@ if str(PROJECT_ROOT) not in sys.path: from muse.flow.adopt import adopt_candidate # noqa: E402 from muse.store import add_review, connect, default_db_path # noqa: E402 - WRITE_ACTIONS = frozenset({"reviews", "revisions", "adopt"})