564 lines
28 KiB
Markdown
564 lines
28 KiB
Markdown
# 目录分层改造 plan
|
||
|
||
日期：2026-08-23
|
||
范围：`agent-example/` 本仓；父仓仅改仍指向本仓旧路径的活文档。
|
||
状态：**已被取代，不再作为执行入口。**
|
||
|
||
> **取代**：后续执行以 [2026-08-24-双底座适配接缝](2026-08-24-双底座适配接缝.md) 为准。
|
||
> **原因**：本文件按「尚未有 `framework/`、先把 58 个 Skill 嵌套搬家」起草；工作树已迁出 `muse/` 与 `framework/`，但依赖方向未分开。DSH 默认 Skill Provider 不递归 `**/SKILL.md`，第 4–5 节把方法 Skill 沉到 `planning/` `writing/` 的发现合同不能原样接到 DSH。架构事实见父仓 [DSH / Pi 与 Muse 的框架业务分离研究](../../../docs/research/dsh-pi-muse-framework-business-separation-2026-08-23.md)。
|
||
> 映射表（第 8 节）仍可当「已经搬到哪」的对照，不作为下一阶段工单。
|
||
|
||
---
|
||
|
||
## 1. 意图
|
||
|
||
把现在根上摊开的一排目录，收成路径能读出来的四层：
|
||
|
||
```text
|
||
L1 framework / .agent / muse / docs 框架、挂载、产品、过程？
|
||
L2 primitives|adapters · sot|content|lifecycle|authority|platform
|
||
L3 C1–C6 或 八领域
|
||
L4 skills / tools / db / studio / chains
|
||
```
|
||
|
||
判定轴不变：`framework/` 拥有 C1–C6（Agent / Skill / MCP / Tool / 可追踪 / 可审计）；Muse 拥有书、人闸、库、额度。`.agent/` 只是运行期挂载面，不是所有权。
|
||
|
||
本改造**搬家 + 改发现合同 + 改文档路径**，不改创作状态机、人闸、CAS、表结构。
|
||
|
||
---
|
||
|
||
## 2. 完成的定义
|
||
|
||
每一阶段结束必须同时满足：
|
||
|
||
1. **磁盘**按该阶段映射表就位（`git mv`，禁止 copy+delete）。
|
||
2. **活文档**里被本阶段碰到的路径全部改完，点击能到达新位置。
|
||
3. **机械门禁绿**：见该阶段验证命令。无自动化绿证据不得声称该阶段完成。
|
||
|
||
全改造完成的总门禁是阶段 G 的路径扫描：活文档和运行时代码里不得再出现已废弃根路径。
|
||
|
||
---
|
||
|
||
## 3. 明确不做
|
||
|
||
- 不改候选状态机、CAS、raw 三件套、事件账本表结构。
|
||
- 不给智能体写库、不合并只读看板与决策通道。
|
||
- 不把额度、Opus 锁、看板、Gate A/B 写进 `framework/`。
|
||
- 不把 `tests/skills/<name>/` 下沉到各 Skill 目录（`parents[N]` 会大面积碎；阶段 G 之后另开）。
|
||
- 不在本改造里拆 Skill 内部为 `schema/` + `scripts/`（那是下一层，不阻塞本次）。
|
||
- 不改 `docs/write-chapter/artifacts/` 运行产物。
|
||
- 不改 git 历史里的旧路径。
|
||
|
||
---
|
||
|
||
## 4. 目标树（压缩）
|
||
|
||
```text
|
||
agent-example/
|
||
├── AGENTS.md
|
||
├── framework/ # C1–C6 原语 + 宿主适配器
|
||
│ ├── primitives/{agent,skill,mcp,tool,trace}/
|
||
│ ├── adapters/{pi,dsh,claude-code,codex}/
|
||
│ └── tests/
|
||
├── .agent/ # 运行期挂载：框架扫、Muse 写
|
||
│ ├── agents/ # 五角色身份
|
||
│ └── skills/{planning,writing,diagnosis}/ # 仅 15 个方法 Skill
|
||
├── muse/
|
||
│ ├── sot/ # 现 muse/sot/
|
||
│ ├── content/{meta,work,entity,paradigm}/
|
||
│ ├── lifecycle/{context,flow,quality,dispatch}/
|
||
│ ├── authority/{db,evidence,tools,studio}/
|
||
│ └── platform/{db,embed,llm}/
|
||
└── docs/ # 过程与历史；本 plan 也在这里
|
||
```
|
||
|
||
58 个 Skill 的落点以第 8 节映射表为准。`skills.json` 的 `skill_path` 是位置事实源。
|
||
|
||
---
|
||
|
||
## 5. 发现合同（先改代码，再搬家）
|
||
|
||
现状假设 Skill 都在 `.agent/skills/<name>/SKILL.md`（`skill_harness.py` 约 891 行：`SKILLS_ROOT / name / "SKILL.md"`）。不先拆掉这个假设，任何嵌套 `git mv` 都会让 58 条 manifest 对账一起红。
|
||
|
||
目标：
|
||
|
||
| 面 | 谁读 | 扫哪里 |
|
||
|---|---|---|
|
||
| 运行期 catalog | 创作智能体 / 框架 Skill 发现 | 只扫 `.agent/skills/**/SKILL.md`（方法 Skill） |
|
||
| 编排索引 | 主代理 / 开发者 | `harness/manifests/skills.json` + 生成的 Muse 索引 |
|
||
| 位置 SoT | 门禁 | `skills.json` 的 `skill_path`（允许任意相对路径） |
|
||
|
||
硬门禁（阶段 C 装上，阶段 D 之后必须绿）：
|
||
|
||
- `invocation=model_routed` → `skill_path` 必须在 `.agent/skills/` 下。
|
||
- `invocation=orchestrated` → `skill_path` 必须在 `muse/` 下。
|
||
- `name` 仍等于 `SKILL.md` 的父目录名。
|
||
- 框架 catalog 不得列出 orchestrated Skill。
|
||
|
||
方法 Skill 闭集（15 个，其余全部 `orchestrated`）：
|
||
|
||
`concept-design` `story-planning` `story-structure` `narrative-momentum` `foreshadow-payoff` `story-ending` `scene-craft` `dialogue-craft` `character-design` `character-presentation` `show-and-omission` `narration-pov` `prose-craft` `theme-and-stance` `novel-diagnosis`
|
||
|
||
当前误标为 `model_routed`、必须改成 `orchestrated` 再迁出 catalog 的：
|
||
|
||
`access-database` `call-content-model` `clean-book-text` `confirm-knowledge-draft` `embed-knowledge` `import-book` `optimize-content-quality` `review-knowledge-cards` `search-knowledge`
|
||
|
||
`search-knowledge` 最终进 `muse/lifecycle/context/`（编排）或工具 server；不进方法 catalog。只读五工具的实现进 `muse/authority/tools/read/`，不是 Skill catalog。
|
||
|
||
---
|
||
|
||
## 6. 阶段
|
||
|
||
依赖：A 可先于一切搬家；B 与 A 可并行；C 依赖 A；D 依赖 A+C；E 依赖 D；F 可与 E 同批但提交分开；G 最后。
|
||
|
||
```text
|
||
A 发现层去扁平假设 → B 拆出 framework/ → C catalog 收口与方法 Skill 嵌套
|
||
→ D 编排 Skill 迁入 muse/ → E 平台与权威目录迁入 muse/ → F SoT 与链接改写 → G 路径门禁收口
|
||
```
|
||
|
||
每阶段一个（或一组紧密）提交。禁止把「尚未改完文档」的搬家标完成。
|
||
|
||
### 阶段 A：发现层去扁平假设（不搬家）
|
||
|
||
意图：运行时与门禁按 `skill_path` 找 Skill，不再假定 `.agent/skills/<name>/SKILL.md`。
|
||
|
||
改：
|
||
|
||
- `harness/skill_harness.py`：删 `expected_path = SKILLS_ROOT / name / "SKILL.md"`；以 manifest `skill_path` 为准；保留「name == 父目录名」。
|
||
- `harness/skills_index.py`：`skill_file` 原样来自 `skill_path`；允许嵌套。
|
||
- `harness/run_selected.py`、`tests/architecture/test_import_boundaries.py`：扫描根改为可配置列表，本阶段仍指向旧根，避免误伤。
|
||
- 增加「从任意子目录走到含 `AGENTS.md` 的仓根」的小函数，后续搬家不再靠 `parents[N]`。`dashboard/`、`tests/skills/*` 里现成的 `parents[1]` / `parents[3]` 本阶段可暂留。
|
||
|
||
文档（本阶段仍是旧路径，只改发现合同的表述）：
|
||
|
||
- `AGENTS.md` §3：写明「物理目录位置是 `skills.json` 的 `skill_path`，不要求一级子目录」。
|
||
- `harness/README.md`、`harness/specs/skill-quality-rubric.md`、`07-Agent与Skill领域.md` §3：把「`.agent/skills/{name}/SKILL.md`」改成「`skill_path` 指向的 `SKILL.md`」。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
.venv/bin/python harness/skill_harness.py --strict
|
||
.venv/bin/python harness/skills_index.py --check
|
||
.venv/bin/python tests/architecture/test_skills_index.py
|
||
.venv/bin/python tests/architecture/test_import_boundaries.py
|
||
```
|
||
|
||
完成：现有扁平布局下上述全绿；再人为把某个 `skill_path` 写成嵌套路径且文件也在嵌套处时，harness 仍接受（可用临时夹具测，测完还原）。
|
||
|
||
### 阶段 B：拆出 `framework/`（Skill 目录先不动）
|
||
|
||
意图：把 C1–C6 从 `dispatch-agent-task/scripts/` 抽到 `framework/`。派发 Skill 仍暂住 `.agent/skills/dispatch-agent-task/`，只改它内部 import。
|
||
|
||
改：
|
||
|
||
| 现在 | 目标 |
|
||
|---|---|
|
||
| `agent_task.py` 中的任务包/白名单/事件归一 | `framework/primitives/{agent,tool,trace}/` |
|
||
| `pi_runner.py` | `framework/adapters/pi/runner.py` |
|
||
| `muse_read_tools_extension.ts` | `framework/adapters/pi/mcp_bridge.ts` |
|
||
| `read_tools.py` | **先**迁到 `framework/` 的旁路？**否**。本阶段仍留在 dispatch 目录，阶段 E 再进 `muse/authority/tools/read/` |
|
||
| `dispatch_agent_task.py` | 仍留 Skill 内，改为调用 `framework` |
|
||
|
||
`FRAMEWORK_ADAPTER_ALLOWLIST` 改为 `framework/adapters/pi/runner.py`。
|
||
|
||
协议暂不删除 `SUPPORTED_AGENT_ROLES` 对五角色的绑定（那是行为收缩，另开）；本阶段只搬家与 import。
|
||
|
||
文档：
|
||
|
||
- `dispatch-agent-task/SKILL.md` 模块表改指向 `framework/…`
|
||
- `边界合同.md` 工具 server / 框架派发的「结构」列补 `framework/adapters/`
|
||
- `07` §2 执行底座：写明「唯一碰框架二进制的位置是 `framework/adapters/`」
|
||
|
||
验证：
|
||
|
||
```bash
|
||
.venv/bin/python tests/architecture/test_import_boundaries.py
|
||
.venv/bin/python tests/skills/dispatch-agent-task/test_dispatch_agent_task.py
|
||
```
|
||
|
||
（dispatch 测试若依赖真实 pi，按现有离线项跑；不把真实模型调用算进本阶段。）
|
||
|
||
### 阶段 C：catalog 收口 + 方法 Skill 嵌套
|
||
|
||
意图：运行期 catalog 只剩 15 个方法 Skill；它们按规划/写作/诊断嵌套。误标 `model_routed` 的改成 `orchestrated`（必须与搬家同提交，否则新门禁自相矛盾）。
|
||
|
||
改：
|
||
|
||
```text
|
||
git mv .agent/skills/concept-design .agent/skills/planning/
|
||
git mv .agent/skills/story-planning .agent/skills/planning/
|
||
git mv .agent/skills/story-structure .agent/skills/planning/
|
||
git mv .agent/skills/narrative-momentum .agent/skills/planning/
|
||
git mv .agent/skills/foreshadow-payoff .agent/skills/planning/
|
||
git mv .agent/skills/story-ending .agent/skills/planning/
|
||
git mv .agent/skills/scene-craft .agent/skills/writing/
|
||
git mv .agent/skills/dialogue-craft .agent/skills/writing/
|
||
git mv .agent/skills/character-design .agent/skills/writing/
|
||
git mv .agent/skills/character-presentation .agent/skills/writing/
|
||
git mv .agent/skills/show-and-omission .agent/skills/writing/
|
||
git mv .agent/skills/narration-pov .agent/skills/writing/
|
||
git mv .agent/skills/prose-craft .agent/skills/writing/
|
||
git mv .agent/skills/theme-and-stance .agent/skills/writing/
|
||
git mv .agent/skills/novel-diagnosis .agent/skills/diagnosis/
|
||
```
|
||
|
||
`skills.json`：15 条 `skill_path` 改嵌套；9 条误标改为 `orchestrated`。生成索引。装上门禁：`model_routed` ⊆ `.agent/skills/`。
|
||
|
||
文档：
|
||
|
||
- `AGENTS.md`：发现入口改为「方法 Skill → `.agent/skills/_index.md`；编排 Skill 仍以 `skills.json` 为总账（阶段 D 后再加 Muse 索引）」。
|
||
- `创作周期与Skill导读.md`：15 个方法 Skill 的链接改到新路径。
|
||
- 各方法 Skill 的 `SKILL.md` 若写了兄弟路径（`../scene-craft`），改成新相对路径。
|
||
- `.agent/skills/_index.md` 用生成器重写，不得手改。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
.venv/bin/python harness/skills_index.py --write && \
|
||
.venv/bin/python harness/skills_index.py --check
|
||
.venv/bin/python harness/skill_harness.py --strict
|
||
.venv/bin/python tests/architecture/test_skills_index.py
|
||
```
|
||
|
||
另加（本阶段落地）：`model_routed` 路径前缀断言。15 个方法 Skill 的 frontmatter 仍是 `model_routed`。
|
||
|
||
### 阶段 D：编排 Skill 迁入 `muse/`
|
||
|
||
意图：43 个 orchestrated Skill 离开 `.agent/skills/`。之后框架即使全量扫挂载面，也看不见写库通道。
|
||
|
||
按第 8 节表 `git mv`。同步：
|
||
|
||
- `harness/manifests/skills.json` 全部 `skill_path`
|
||
- `tests/skills/<name>/` **不迁**（仍按 Skill 名平铺）；测试内的 `Path(".agent") / "skills" / "<name>"` 改为读 manifest 或仓根查找函数
|
||
- `dashboard/decision_channel.py`、`dashboard/lesson_confirm.py` 的 `SKILLS = ROOT / ".agent" / "skills"` 改为新路径（或经 manifest 解析）
|
||
- `test-inventory.json` 里写死的 `.agent/skills/...` 路径
|
||
- 生成第二份索引：`muse/sot/skills-index.md` 或 `muse/_skills_index.md`（编排发现）；`.agent/skills/_index.md` 只含 15 个方法 Skill
|
||
|
||
文档：
|
||
|
||
- `AGENTS.md` §3 目录树与 Skill 责任方表：编排 Skill 的路径改 `muse/…`
|
||
- `meta/chains/README.md`（此时仍在旧处）：功能 Skill 链接改新路径
|
||
- `07` §3：系统能力 Skill 的磁盘位置改为 `muse/…/skills/<name>/SKILL.md`
|
||
- 每只被迁 Skill 的 `SKILL.md`、其它 Skill 对它的相对链接
|
||
- `创作周期与Skill导读.md` 全部编排 Skill 卡片链接
|
||
- `harness/README.md`、`harness/specs/*`
|
||
|
||
验证：同上 harness 三条 + import boundaries + 抽跑 `tests/skills/decide-candidate`、`write-next-chapter`、`assemble-context`、`dispatch-agent-task` 这些硬编码过路径的测试。
|
||
|
||
完成：`.agent/skills/` 下只剩 `planning/` `writing/` `diagnosis/` `_index.md`。
|
||
|
||
### 阶段 E：平台与权威目录迁入 `muse/`
|
||
|
||
```text
|
||
git mv db muse/authority/db
|
||
git mv dashboard muse/authority/studio # 随后在 studio 内再分成 read/ 与 write/
|
||
git mv meta/schemas muse/content/meta/schemas
|
||
git mv meta/chains muse/lifecycle/flow/chains
|
||
git mv knowledge muse/content/entity/sources
|
||
git mv humanization muse/lifecycle/quality/humanization
|
||
git mv harness muse/lifecycle/quality/harness
|
||
git mv muse-db muse/platform/db
|
||
git mv muse-llm muse/platform/llm
|
||
git mv muse-embed muse/platform/embed
|
||
```
|
||
|
||
`dashboard/` 进 `studio/` 后立刻拆：
|
||
|
||
```text
|
||
muse/authority/studio/read/ # 现 server.py :8765
|
||
muse/authority/studio/write/decision # 现 decision_channel.py :8767
|
||
muse/authority/studio/write/lesson # 现 lesson_confirm.py :8766
|
||
```
|
||
|
||
`read_tools.py` 从 dispatch Skill 迁到 `muse/authority/tools/read/`（可按五工具分子目录，本阶段至少落到 `read/` 包）。Pi 的 `mcp_bridge.ts` 只保留桥，SQL 不回去。
|
||
|
||
`requirements.txt`：
|
||
|
||
```text
|
||
-e ./muse/platform/db
|
||
-e ./muse/platform/llm
|
||
-e ./muse/platform/embed
|
||
-e ./muse/lifecycle/quality/humanization
|
||
```
|
||
|
||
包名 `muse-db` / `muse-llm` / `muse-embed` / `muse-deai` 不变。迁完后 `uv pip install -r requirements.txt` 重装 editable。
|
||
|
||
`test_import_boundaries.py` 的 `ACTIVE_RUNTIME_ROOTS`、`FORBIDDEN_PATHS`、扫描范围改新根。`run_selected.py` 扫描根改新路径。humanization 测试里 `parents[2]` / `sys.path` 指向 `humanization/src` 的，改到新树（或继续靠已安装包 `import deai`，与现门禁一致）。
|
||
|
||
文档：凡写 `db/` `dashboard/` `humanization/` `harness/` `meta/` `muse-db/` `knowledge/` 作为**仓内路径**的活文档，全部改。包括 `db/表映射.md`、`可视化模块合同.md`、`08`、看板 docstring、`harness/README.md`（此时已在 quality/harness 下，相对链接要重算）。
|
||
|
||
验证：
|
||
|
||
```bash
|
||
uv pip install --python .venv/bin/python -r requirements.txt
|
||
.venv/bin/python -c "import muse_db, muse_llm, muse_embed, deai"
|
||
.venv/bin/python tests/architecture/test_import_boundaries.py
|
||
.venv/bin/python muse/lifecycle/quality/harness/skill_harness.py --strict
|
||
.venv/bin/python muse/authority/studio/read/test_server_display.py
|
||
```
|
||
|
||
（具体测试文件随 `git mv` 走；命令以搬完后的真实路径为准。）
|
||
|
||
### 阶段 F：SoT 迁到 `muse/sot/` + 全量链接
|
||
|
||
```text
|
||
git mv muse/sot muse/sot
|
||
```
|
||
|
||
`.agent/docs/` 若空则删；`.agent/_index.md` 只保留挂载面（agents / skills），SoT 指针改 `muse/sot/`。
|
||
|
||
代码：
|
||
|
||
- `muse_role_contract.py`：`ROLE_CONTRACT_RELATIVE_PATH = Path("muse") / "sot" / "角色合同.md"`
|
||
- dispatch 测试里 `roleContractSource` 断言同步
|
||
- `dashboard/server.py` 头部合同路径
|
||
|
||
**相对链接**：SoT 从 `muse/sot/` 迁走后，所有 `../muse/sot/…` 和 SoT 内部链到 `../../../.agent/skills`、`../../../../docs/` 的链接按新深度重写。这是本阶段主工作量。
|
||
|
||
活文档清单见第 7 节。本阶段结束时第 7 节每一条都指向新路径。
|
||
|
||
父仓：`design-docs/流程-02B-普通用户系统处理流程(系统视角).md` 中
|
||
|
||
`../agent-example/muse/sot/domains/02-实体领域.md`
|
||
|
||
改为
|
||
|
||
`../agent-example/muse/sot/domains/02-实体领域.md`
|
||
|
||
（父仓单独提交，不和本仓混。）
|
||
|
||
验证：阶段 G 的扫描在本阶段应已接近全绿；允许本 plan 文件和「旧路径」对照表暂时命中。
|
||
|
||
### 阶段 G：路径门禁收口
|
||
|
||
装常驻门禁 `tests/architecture/test_layout_paths.py`（名称可改，职责不可改）：
|
||
|
||
1. 根目录只允许：`AGENTS.md` `CLAUDE.md` `README.md` `requirements.txt` `.agent/` `framework/` `muse/` `docs/` `tests/` 以及既有的 `.git` `.venv` `.gitignore` 等仓务。不得再出现 `db/` `dashboard/` `harness/` `humanization/` `meta/` `muse-db/` `muse-llm/` `muse-embed/` `knowledge/`。
|
||
2. `.agent/skills/` 下除 `_index.md` 外只有 `planning/` `writing/` `diagnosis/`。
|
||
3. `invocation` 与路径前缀符合第 5 节。
|
||
4. 活文档与运行时代码扫描：下列字符串不得作为路径出现（排除 `docs/plans/` 本文件、`docs/write-chapter/artifacts/`）：
|
||
|
||
```text
|
||
muse/sot
|
||
.agent/skills/dispatch-agent-task
|
||
.agent/skills/decide-candidate
|
||
.agent/skills/access-database
|
||
.agent/skills/write-next-chapter
|
||
humanization/src
|
||
-e ./muse-db
|
||
-e ./humanization
|
||
dashboard/server.py
|
||
db/ddl/
|
||
harness/manifests/skills.json
|
||
meta/chains/
|
||
```
|
||
|
||
（列表以搬完后的废弃前缀为准，装门禁时用生成器从「映射表旧路径」收，避免手写漏项。）
|
||
|
||
5. Markdown 链接目标文件必须存在（死链失败关闭）。覆盖：`muse/sot/**/*.md` `AGENTS.md` `README.md` `.agent/**/*.md` `muse/**/*.md` 中仍被 SoT 引用的 `docs/*.md`。
|
||
|
||
全量验证（阶段 G 完成判据）：
|
||
|
||
```bash
|
||
.venv/bin/python tests/architecture/test_layout_paths.py
|
||
.venv/bin/python tests/architecture/test_import_boundaries.py
|
||
.venv/bin/python tests/architecture/test_skills_index.py
|
||
.venv/bin/python muse/lifecycle/quality/harness/skill_harness.py --strict
|
||
```
|
||
|
||
再按 `test-inventory.json` 跑与路径相关的离线实现测试（至少 dispatch、decide-candidate、assemble-context、write-next-chapter、看板 display）。不把真实模型 / 真库写入当成本次改造的完成证据；碰到因路径而找不到夹具的，修路径后再跑原来的离线项。
|
||
|
||
---
|
||
|
||
## 7. 文档更新清单（活文档，必须改）
|
||
|
||
「活」= 现在仍被当作合同、入口或教学地图阅读。过程 plan 与运行产物不在此列。
|
||
|
||
### 7.1 入口（阶段 C–F 随目录改，F 收齐）
|
||
|
||
| 文件 | 改什么 |
|
||
|---|---|
|
||
| `AGENTS.md` | 目录树、SoT 表、Skill 发现入口（两份索引）、责任方表路径、§3/§11 中的 `.agent/skills` 假设 |
|
||
| `README.md` | 目录树、SoT 顺序 |
|
||
| `.agent/_index.md` | 挂载面 vs `muse/sot` |
|
||
| `.agent/docs/_index.md` | 若目录删除则本文件删除或改为跳转 |
|
||
|
||
### 7.2 SoT（阶段 F 为主，此前被碰到的链接提前改）
|
||
|
||
| 文件 | 改什么 |
|
||
|---|---|
|
||
| `muse/sot/_index.md`（现 architecture/_index.md） | 相对链接深度 |
|
||
| `边界合同.md` | 结构列：`framework/`、`muse/authority/tools`、`muse/authority/studio` |
|
||
| `角色合同.md` | `promptFile` 仍是 `.agent/agents/*.md`；其它仓内路径 |
|
||
| `可视化模块合同.md` | `dashboard/` → studio；`db/表映射.md` |
|
||
| `创作周期与Skill导读.md` | 全部 Skill 链接 + 导语里的 58 只平铺假设；方法 / 编排两份索引 |
|
||
| `domains/_index.md` | Git 权威那一行的 `meta/`、相对链到 `docs/` |
|
||
| `domains/01`–`08` | 文中磁盘路径与交叉链接深度 |
|
||
| `07` §3 | `{name}` 扁平公式 |
|
||
|
||
### 7.3 规范与登记
|
||
|
||
| 文件 | 改什么 |
|
||
|---|---|
|
||
| `harness/README.md` 及 specs（迁后在 quality/harness） | 适用范围、Owner 路径 |
|
||
| `skills.json` / 生成的两份 `_index.md` | 每条 `skill_path` |
|
||
| `meta/chains/README.md`（迁后 flow/chains） | humanization 链接、05 链接、功能 Skill 路径 |
|
||
| `db/表映射.md` `连接信息.md` | 自身相对位置；`db/ddl/` 字面 |
|
||
| 各 `SKILL.md` | 入口命令、相对 `scripts/`、兄弟 Skill 链接 |
|
||
| `.agent/agents/*.md` | 若写了 Skill 路径则改（现多为名字不带路径，抽查） |
|
||
|
||
### 7.4 仍被 SoT 引用的 `docs/` 设计稿
|
||
|
||
这些不是领域 SoT，但链还活着，不改就是死链：
|
||
|
||
- `docs/2026-07-14-参考书作品面数据入库方案.md`
|
||
- `docs/2026-07-16-升格卡改造设计.md`
|
||
- `docs/2026-07-30-落库与看板设计.md`
|
||
- `docs/2026-08-01-评测harness改造设计.md`
|
||
- `docs/2026-08-19-craft-distillation-trace.md`
|
||
- `docs/2026-08-20-skill-质量审查与复利改造清单.md`
|
||
- `docs/2026-08-20-质量收敛环运行手册.md`
|
||
- `docs/acceptance/` 下仍引用旧路径的验收记录
|
||
|
||
### 7.5 父仓
|
||
|
||
| 文件 | 改什么 |
|
||
|---|---|
|
||
| `design-docs/流程-02B-普通用户系统处理流程(系统视角).md` | `agent-example/muse/sot/domains/02-实体领域.md` → `muse/sot/domains/…` |
|
||
|
||
开工前再扫一遍：
|
||
|
||
```bash
|
||
rg -n 'agent-example/\.agent/docs|agent-example/\.agent/skills|agent-example/db/|agent-example/dashboard' \
|
||
--glob '!agent-example/docs/plans/**' --glob '!**/artifacts/**'
|
||
```
|
||
|
||
新命中补进本表，禁止口头「应该没有了」。
|
||
|
||
### 7.6 不改
|
||
|
||
- 本文件（对照表需要旧路径）
|
||
- `docs/write-chapter/artifacts/`
|
||
- 已删除的整体收敛 plan（git 历史）
|
||
|
||
---
|
||
|
||
## 8. Skill 映射表（阶段 C/D 执行 SoT）
|
||
|
||
### 8.1 方法 Skill → `.agent/skills/`（catalog）
|
||
|
||
| name | 目标 |
|
||
|---|---|
|
||
| concept-design | `.agent/skills/planning/concept-design/` |
|
||
| story-planning | `.agent/skills/planning/story-planning/` |
|
||
| story-structure | `.agent/skills/planning/story-structure/` |
|
||
| narrative-momentum | `.agent/skills/planning/narrative-momentum/` |
|
||
| foreshadow-payoff | `.agent/skills/planning/foreshadow-payoff/` |
|
||
| story-ending | `.agent/skills/planning/story-ending/` |
|
||
| scene-craft | `.agent/skills/writing/scene-craft/` |
|
||
| dialogue-craft | `.agent/skills/writing/dialogue-craft/` |
|
||
| character-design | `.agent/skills/writing/character-design/` |
|
||
| character-presentation | `.agent/skills/writing/character-presentation/` |
|
||
| show-and-omission | `.agent/skills/writing/show-and-omission/` |
|
||
| narration-pov | `.agent/skills/writing/narration-pov/` |
|
||
| prose-craft | `.agent/skills/writing/prose-craft/` |
|
||
| theme-and-stance | `.agent/skills/writing/theme-and-stance/` |
|
||
| novel-diagnosis | `.agent/skills/diagnosis/novel-diagnosis/` |
|
||
|
||
### 8.2 编排 Skill → `muse/`
|
||
|
||
| name | 目标 |
|
||
|---|---|
|
||
| write-next-chapter | `muse/content/work/skills/generate/write-next-chapter/` |
|
||
| expand-scene | `muse/content/work/skills/generate/expand-scene/` |
|
||
| polish-prose | `muse/content/work/skills/generate/polish-prose/` |
|
||
| rewrite-selection | `muse/content/work/skills/generate/rewrite-selection/` |
|
||
| decide-candidate | `muse/content/work/skills/sovereignty/decide-candidate/` |
|
||
| import-book | `muse/content/entity/skills/ingest/import-book/` |
|
||
| clean-book-text | `muse/content/entity/skills/ingest/clean-book-text/` |
|
||
| deconstruct-book | `muse/content/entity/skills/ingest/deconstruct-book/` |
|
||
| extract-work-knowledge | `muse/content/entity/skills/ingest/extract-work-knowledge/` |
|
||
| inspect-parse-health | `muse/content/entity/skills/ingest/inspect-parse-health/` |
|
||
| backup-work-extraction | `muse/content/entity/skills/ingest/backup-work-extraction/` |
|
||
| repair-work-extraction | `muse/content/entity/skills/ingest/repair-work-extraction/` |
|
||
| reset-work-extraction | `muse/content/entity/skills/ingest/reset-work-extraction/` |
|
||
| extract-chapter-knowledge | `muse/content/entity/skills/extract/extract-chapter-knowledge/` |
|
||
| review-knowledge-cards | `muse/content/entity/skills/review/review-knowledge-cards/` |
|
||
| confirm-knowledge-draft | `muse/content/entity/skills/sovereignty/confirm-knowledge-draft/` |
|
||
| freeze-context | `muse/lifecycle/context/skills/freeze-context/` |
|
||
| assemble-context | `muse/lifecycle/context/skills/assemble-context/` |
|
||
| search-knowledge | `muse/lifecycle/context/skills/search-knowledge/` |
|
||
| embed-knowledge | `muse/lifecycle/context/skills/embed-knowledge/` |
|
||
| design-story-foundation | `muse/lifecycle/flow/skills/book/design-story-foundation/` |
|
||
| merge-story-candidates | `muse/lifecycle/flow/skills/book/merge-story-candidates/` |
|
||
| plan-story | `muse/lifecycle/flow/skills/book/plan-story/` |
|
||
| plan-chapter | `muse/lifecycle/flow/skills/chapter/plan-chapter/` |
|
||
| adjudicate-quality-gate | `muse/lifecycle/quality/skills/mechanical/adjudicate-quality-gate/` |
|
||
| check-content-consistency | `muse/lifecycle/quality/skills/semantic/check-content-consistency/` |
|
||
| score-content-quality | `muse/lifecycle/quality/skills/judge/score-content-quality/` |
|
||
| optimize-content-quality | `muse/lifecycle/quality/skills/judge/optimize-content-quality/` |
|
||
| evaluate-frozen-replay | `muse/lifecycle/quality/skills/replay/evaluate-frozen-replay/` |
|
||
| replay-writer-gate | `muse/lifecycle/quality/skills/replay/replay-writer-gate/` |
|
||
| load-replay-reference-work | `muse/lifecycle/quality/skills/replay/load-replay-reference-work/` |
|
||
| establish-voice-baseline | `muse/lifecycle/quality/humanization/skills/establish-voice-baseline/` |
|
||
| prevent-ai-flavor | `muse/lifecycle/quality/humanization/skills/prevent-ai-flavor/` |
|
||
| diagnose-ai-flavor | `muse/lifecycle/quality/humanization/skills/diagnose-ai-flavor/` |
|
||
| revise-ai-flavor | `muse/lifecycle/quality/humanization/skills/revise-ai-flavor/` |
|
||
| capture-ai-flavor-cases | `muse/lifecycle/quality/humanization/skills/capture-ai-flavor-cases/` |
|
||
| promote-ai-flavor-rule | `muse/lifecycle/quality/humanization/skills/promote-ai-flavor-rule/` |
|
||
| dispatch-agent-task | `muse/lifecycle/dispatch/skills/dispatch-agent-task/` |
|
||
| record-run-evidence | `muse/authority/evidence/skills/record-run-evidence/` |
|
||
| access-database | `muse/authority/evidence/skills/access-database/` |
|
||
| call-content-model | `muse/platform/llm/skills/call-content-model/` |
|
||
| execute-role-task | `muse/platform/llm/skills/execute-role-task/` |
|
||
| refresh-runtime-probe | `muse/platform/llm/skills/refresh-runtime-probe/` |
|
||
|
||
15 + 43 = 58。增删 Skill 先改本表再 `git mv`。
|
||
|
||
### 8.3 非 Skill 目录
|
||
|
||
| 现在 | 目标 |
|
||
|---|---|
|
||
| `.agent/agents/` | 不动 |
|
||
| `muse/sot/` | `muse/sot/` |
|
||
| `db/` | `muse/authority/db/` |
|
||
| `dashboard/server.py` | `muse/authority/studio/read/` |
|
||
| `dashboard/decision_channel.py` | `muse/authority/studio/write/decision/` |
|
||
| `dashboard/lesson_confirm.py` | `muse/authority/studio/write/lesson/` |
|
||
| `meta/schemas/` | `muse/content/meta/schemas/` |
|
||
| `meta/chains/` | `muse/lifecycle/flow/chains/` |
|
||
| `knowledge/` | `muse/content/entity/sources/` |
|
||
| `humanization/` | `muse/lifecycle/quality/humanization/` |
|
||
| `harness/` | `muse/lifecycle/quality/harness/` |
|
||
| `muse-db/` | `muse/platform/db/` |
|
||
| `muse-llm/` | `muse/platform/llm/` |
|
||
| `muse-embed/` | `muse/platform/embed/` |
|
||
| `dispatch …/read_tools.py` | `muse/authority/tools/read/` |
|
||
| `dispatch …/pi_runner.py` | `framework/adapters/pi/runner.py` |
|
||
| `tests/skills/` `tests/architecture/` | 不动 |
|
||
| `docs/` | 不动 |
|
||
|
||
---
|
||
|
||
## 9. 约束
|
||
|
||
1. **先改发现，再搬家。** 违反则 harness 会用旧公式打红 58 条，看起来像「目录改造失败」，其实是门禁还停在扁平假设。
|
||
2. **文档跟提交走。** 不允许「代码已迁、README 下一批再改」。阶段完成清单含第 7 节被本阶段碰到的行。
|
||
3. **`git mv`。** 需要嵌套时先 `mkdir -p` 再 `git mv`。
|
||
4. **invocation 与目录同提交**（阶段 C）。
|
||
5. **包名稳定、路径变。** `import muse_db` 不变；变的是 `-e ./…`。
|
||
6. **测试按 Skill 名平铺留下**，避免本次范围膨胀。
|
||
7. 阶段 G 的路径门禁是本改造的完成牙齿；没有它只能算「搬过」，不能算完成。
|
||
|
||
---
|
||
|
||
## 10. 开工顺序（执行时从这里抄）
|
||
|
||
1. 阶段 A：harness 去扁平 + 三份发现文档。
|
||
2. 阶段 B：`framework/` + allowlist + dispatch SKILL.md。
|
||
3. 阶段 C：15 个 `git mv` + 9 条 invocation + 生成索引 + catalog 门禁 + 导读链接。
|
||
4. 阶段 D：43 个 `git mv` + manifest + 看板/测试里的 Skill 根 + AGENTS.md 双索引。
|
||
5. 阶段 E：平台/权威 `git mv` + requirements + 重装 + 工具 server 迁出 dispatch。
|
||
6. 阶段 F：`muse/sot` + `ROLE_CONTRACT_RELATIVE_PATH` + 第 7 节全表 + 父仓 流程-02B。
|
||
7. 阶段 G：`test_layout_paths.py` 绿。
|