Skip to content

[S8/PR1] fix appendix generators A/B/D/F + E↔C16 link#75

Merged
luyao618 merged 5 commits into
mainfrom
agent/cc-dev/9847d7c0
May 27, 2026
Merged

[S8/PR1] fix appendix generators A/B/D/F + E↔C16 link#75
luyao618 merged 5 commits into
mainfrom
agent/cc-dev/9847d7c0

Conversation

@luyao618
Copy link
Copy Markdown
Owner

Summary

Per YAO-154 (S8) review consensus, PR1 in the 2-PR split. PR2 will land C's hooks-trigger-map.json + first 15 hook events.

附录 问题 修复
A feature-gated = 0 与表格自相矛盾 gate 检测从段内 require(...).XxxTool 单写法扩展到 require('./tools/<dir>/<file>.js').XxxTool 通配,并支持 cronTools = feature(...) ? [require(...).A, require(...).B] : [] 数组形态。重算 0 → 19 feature-gated
B "静态引用 = 3" 旧 regex 要求 import { ... } 命名导入;commands.ts 主要用 import foo from './commands/foo/...' 默认导入。改为同时匹配三种 import 形态。重算 3 → 92 静态 import + 16 require-only。新增"条件 require 装载"小节
D 列名 displayName 截断 源码 BuiltInAgentDefinitiondisplayName 字段。列名改为 whenToUse(首句节选,详见源码),去掉 80 字符硬截断;同时解析 whenToUse: SOME_CONSTANT 引用,Explore / verification 现在能渲染出首句
F "白名单 5 项" vs 反查表只有 4 个 "—" 重写孤儿/白名单脚注,明确白名单中部分目录(utils/context/)仍被多章节覆盖,反查列因此不为空、也不显示 ,避免"5 vs 4"误读
E 与第 16 章重复 加双向 link:E 顶部指向 C16,C16 顶部指向 E(定位互补:E 速查、C16 叙事)

scripts/orphan-allowlist.txt 实际内容

按 @麻薯 硬约束附实际清单,证实"白名单 5 项"数字正确:

# scripts/orphan-allowlist.txt
# 一级源码目录在 archive/V2-REVISION-SPEC.md §6.2 中未被任何 v2 章节覆盖,但属预期免覆盖。
# 每行一项;# 之后为注释。每条新增必须配 PR 描述里的理由。

# 进程内通用工具堆,跨章共用,不单独成章
utils
# 类型/接口聚合,被章节按需引用
types
# 启动期 process state,C02 一笔带过即可
bootstrap
# 顶层 IPC 主入口已在 C24/C33 串讲;moreright 是右侧栏装饰
moreright
# UI / 业务上下文 hook,分散在 C19/C20/C28 等章
context

bun scripts/gen-module-matrix.ts --check-orphansOK no orphan dirs (covered=31, allowlisted=5)

重生成后的关键数字

[A] wrote docs/appendix/A.md + manifest (59 items: 9 family / 31 leaf / 19 feature-gated)
[B] wrote docs/appendix/B.md + manifest (dirs=86, files=15)
[D] wrote docs/appendix/D.md + manifest (6 agents)
[E] wrote docs/appendix/E.md + manifest (wire=7, default=4, fg=2)
[F] wrote docs/appendix/F.md + manifest (chapters=34, top_dirs=35, orphans=0)

Test plan

  • bun scripts/gen-{tool,commands,agents,tasktypes,module-matrix}.ts --source-path … 全部跑通
  • bun run check:source-commits ✓ 6 个文件全部指向 290fdc94
  • bun run check:no-fuzzy / check:no-revision-codenames / check:no-frontmatter / check:no-spec-jargon
  • bun run check:orphanscovered=31, allowlisted=5, orphans=0
  • CI 上的 prose-diff / heading-preservation / code-ratio / section-titles 闸(需 base ref,本地未跑)

范围说明

附录 C 不在本 PR 内。C 的 hooks-trigger-map.json + 首批 15 事件走 PR2。剩余 12 事件已建 follow-up YAO-155 跟踪(需 bundler 反混淆)。

Yao Lu and others added 5 commits May 27, 2026 17:43
Per YAO-154 (S8) review consensus. PR1 in 2-PR split; PR2 will add
C's hooks-trigger-map.json + 15 hook events.

- gen-tool-table.ts (A): tighten feature-gated detection. Previous
  per-segment scan only caught `require(...).XxxTool` single-assignment
  form, missing arrays like `cronTools = feature(...) ? [require(...).X,
  require(...).Y] : []` and missing the gate keyword for every entry.
  Now scans every `require('./tools/<dir>/<file>.js').XxxTool` and
  attributes it to the enclosing `const NAME =` statement if that
  statement contains a gate keyword. Recount: 0 → 19 feature-gated.

- gen-commands-table.ts (B): the static-import regex required `{...}`
  named-import braces, but commands.ts uses mostly `import foo from
  './commands/foo/...'` (default imports). Recount: 3 → 92 statically
  imported. Also report dynamic-only require() count (16) and any
  directory unreferenced by commands.ts (0). Adds a "条件 require 装载"
  section.

- gen-agents-table.ts (D): drop the synthetic `displayName` column
  (source `BuiltInAgentDefinition` has no such field). Replace with
  `whenToUse(首句节选)`, no 80-char truncation, and resolve
  `whenToUse: SOME_CONSTANT` references against the same file and
  sibling built-in/ files (Explore / verification now render).

- gen-module-matrix.ts (F): rewrite the orphan/whitelist footer to
  spell out why allowlisted dirs (utils/, context/) still show
  chapters in the reverse index — preempts the "5 vs 4" confusion
  flagged in review.

- gen-tasktypes-table.ts (E) + 16-...md: add bi-directional link
  between appendix E (quick reference) and Chapter 16 (narrative).

- Regenerated A.md / B.md / D.md / E.md / F.md + matching manifests.

Local checks passing: check:source-commits, check:no-fuzzy,
check:no-revision-codenames, check:no-frontmatter, check:no-spec-jargon,
check:orphans (covered=31, allowlisted=5, orphans=0).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: multica-agent <github@multica.ai>
…lit, D no truncation

A: split family/leaf/feature-gated into orthogonal family(bool) + register(default|feature-gated|—)
   - 不再互斥归类,feature-gated 工具可同时是 family
   - 最终 59 项:family=40, register: default=31 / feature-gated=19 / —=9

B: 把 commands.ts import 计数拆成目录/文件两个维度,避免把 commands/commit.js 当成目录
   - 静态 import 目录=82(与 OC-Dev 的 82 口径对齐)
   - 静态 import 文件=10
   - 条件 require 目录=3,文件=6

D: whenToUse 改用同种引号闭合的正则(之前 `['"`]` 互通闭合,被 user's / "Can Claude..." 提前截断)
   - 6/6 agents 都有完整 whenToUse 原文,不再截断
Co-authored-by: multica-agent <github@multica.ai>
OC-R 12:06 复审:F.md:88-90 措辞自相矛盾——反查表用 `—(孤儿或入白名单)`
但 L90 又称 `—` 仅出现在未覆盖且不在白名单内的目录上(当前为 0),与表格内
4 个 `—` 行冲突。

修:
- 反查表的 `—` 改为单义"未被任何 v2 章节直接覆盖"
- 脚注澄清 `orphans` = `—` 行剔除白名单条目
- utils/ 被章节叙事覆盖故不出现 `—`,属于"白名单兜底但实际不需要",无矛盾

Co-authored-by: multica-agent <github@multica.ai>
- docs/appendix/F.md: rename `## 孤儿目录与白名单` back to `## 孤儿目录`
  (v1 heading preserved; whitelist explanation kept in body paragraph)
- scripts/gen-module-matrix.ts: regenerate with the v1 heading
- docs/16-...: revert renumbered headings (`## 附 A`, `### 4.x`) that
  conflicted with main's `## 三点五` / `### 3.5.x`. Keep only the
  bidirectional link addition to appendix E in the chapter header.

Local: bun scripts/check-heading-preservation.ts --base origin/main → OK
on all 6 changed docs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: multica-agent <github@multica.ai>
Co-authored-by: multica-agent <github@multica.ai>
@luyao618 luyao618 merged commit 3e8edb4 into main May 27, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant