Skip to content

Commit eebcef8

Browse files
tzhouamclaude
andcommitted
kb init: modules stage (module map cards and routes)
Stage 2 of kb init (design v3 §7.1-7.2): route every code module. - init_stages: the skeleton's flow becomes a _Stage base shared by every stage (pin, record, rule screening and placement, the deterministic checks as _conclude, the publication); _Skeleton keeps only its own steps. New: the stage chain. Each earlier stage must be merged (record published and gh pr view MERGED, so main holds it), or, for a dry run of this stage, dry-run: its snapshot is overlaid on main as the base and handed to the knowledge validators with this stage's change. A stage with nothing to change is recorded "empty", not blocked. Later stages keep the earlier stages' pin unless --pin says otherwise. - init_modules: scan_modules_at_depth at the pin (language from the adapter's repo.language; none or unknown -> no scan, checklist). A module an owner partly reaches is absorbed: its prefix is appended to that owner's scope_prefixes. Every other module gets one bounded generator call (file names, signatures, leading docstrings, never bodies) and a map card: a prose page (type architecture) in an existing components/<group>/ (index append-only) or a new group with its own _index.md and route owner, linked upward. Sections are bold labels: the knowledge format reads any "## <Word>" heading as a rule ID. The route table is only appended to (routes_append_only). Budget or card cap -> the cards written so far still make a PR; the rest is listed. - InitRecord.coverage: the stage's coverage report, rendered as a before/after table in the PR body. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 4115751 commit eebcef8

6 files changed

Lines changed: 1167 additions & 204 deletions

File tree

‎doc/architecture/SPEC/kb_service.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -370,5 +370,29 @@ x 必须为正。因阈值停下的调用(`stop_reason="max_budget"`)→ `Mo
370370
`blocked` 并保留它,重跑时直接完成**同一个**发布(同输入重建出同一提交,已推送的分支与已开的 PR 都复用,不再调模型)。
371371
dry run 每次整体替换输出目录,不残留上一次的页面;有待完成的发布时拒绝 dry run(不覆盖它)。模型提出的 owner 页必须
372372
是本仓库目录下已有或本阶段创建的页面,指向其他仓库的页面一律丢弃并记入 notes。仓库标签不在 `doc/knowledge/SCHEMA.md` 分类法里、种子不存在、生成模型不可用或无价格 → 记录为 `blocked`,
373-
不产生 PR。同输入摘要重跑直接返回记录;已发布记录的输入变了则拒绝。`modules`/`deepen`/`harvest-calibration` 抛
373+
不产生 PR。同输入摘要重跑直接返回记录;已发布记录的输入变了则拒绝。`deepen`/`harvest-calibration` 抛
374374
`NotImplementedError`。测试:`test_kb_init_skeleton.py`、`test_kb_init_config.py`。
375+
376+
## 2026-09-30 kb init:阶段共用流程与阶段 2(modules)
377+
- `init_stages._Stage`:各阶段共用的流程——钉点、记录、前序阶段链、规则筛查与落位、确定性检查(`_conclude`)、发布;
378+
子类只设 `STAGE` 并实现 `_build`。**阶段链**(设计 §9):前序每个阶段都必须已合并(记录为 `published` 且
379+
`gh pr view` 为 `MERGED`,此时 main 已含它),或者(仅当本阶段是 dry run 时)是 dry run——其快照(`<stage>-dryrun/tree`)
380+
叠加在 main 上作为本阶段的基底,并随本阶段的变更一起交给知识树校验器;`empty`(没有可改的)直接放行。未合并、只 dry
381+
run 却要发布、未运行或处于 blocked/publishing 的前序阶段 → `blocked`,不调模型。后续阶段缺省沿用前序阶段的钉点
382+
(`--pin` 可改,改了记入 notes);链的状态进入输入摘要。阶段没有任何改动时记为 `empty`(不是错误)。
383+
`InitRecord.coverage` 是阶段的覆盖率报告,PR 正文渲染成 before/after 表。适配器 manifest 从前序 dry run 的改动或知识
384+
仓库基点读取(`adapters/<adapter 目录名>/manifest.yaml`);`repo.language` 决定模块扫描的语言。
385+
- `init_modules`(阶段 2):在钉点树上 `scan_modules_at_depth`(`source_roots`、`module_depth`、`min_module_loc`、
386+
`exclude`;adapter 未声明语言或语言未知 → 不扫描,进清单)。按当前 `_routes.yaml` 算模块覆盖率。未覆盖的模块由深到浅:
387+
已被某个 owner 部分覆盖的,**吸收**进覆盖其文件最多的 owner(只在该 owner 的 `scope_prefixes` 末尾追加模块目录;仓库
388+
根模块因前缀不能表达,逐文件追加);完全无人覆盖的,每个模块一次有界的生成调用(文件名、符号签名、文件开头的 docstring
389+
或注释块,字节上限;从不给函数体:签名正则匹配整行,`declaration` 截掉函数体——
390+
花括号语言(JavaScript、Go、Rust)在整行**最早**的 `{`/`=>`/`;`/单独的 `=` 处截断,不去词法分析字符串、注释或正则字面量
391+
(函数体不可能出现在它们之前,默认值可能被截短,这是失败即关闭的取舍);Python 在括号、字符串与行尾 `#` 注释之外的
392+
第一个 `:` 处截断;单行函数也只留声明)写一张**地图卡片**:prose 页(`type: architecture`),目的、入口、关键文件(只保留该
393+
模块真实存在的文件)、要读的文档(只保留文档集里的文件)、路由前缀;分节用加粗标签而非标题(知识格式把任何
394+
`## <Word> …` 标题当作规则 ID)。卡片进入组:已有的 `components/<group>/`(入口页只追加链接,已有 owner 只追加前缀),
395+
或新组(新目录、自己的 `_index.md` 与新的路由 owner),新组由上级入口页链接;`components/` 不存在时新建其入口页并由
396+
仓库入口页链接;`components/` 已存在却没有入口页时组直接放在仓库目录下。`_routes.yaml` 只追加(保留开头注释块,
397+
`routes_append_only` 校验不重排、不改名、不删除)。预算用完或超过卡片上限时,已写的卡片照常成 PR,剩下的模块进
398+
`unfinished`;报告里列出仍无路由的模块。测试:`test_kb_init_modules.py`。

0 commit comments

Comments
 (0)