117 lines
8.1 KiB
Markdown
117 lines
8.1 KiB
Markdown
# octopus Core（工作流标准公共层）
|
||
|
||
`core/` 是工作流体系标准化后的**公共 Core**：自包含的规则、技能、
|
||
清单、模板、schema 与适配器层。`.octopus/` 下的对应文件是**消费副本**
|
||
（dogfood 实例），`examples/` 仅承载叙事性示例。
|
||
|
||
## 不变量 C-1：Core 不引用实例
|
||
|
||
- Core 内的工件**不得引用** `examples/` 或任何实例专有路径；`core/adapters/**`
|
||
例外——adapter 目录承载后端绑定的 API 形态（工具名、端点），但仍
|
||
**禁止实例机密与实例专有地址**（内网 IP、实例主机名、实例配置路径）。
|
||
- 引用方向是**单向的**：`examples/` 与实例层可以引用 Core，Core 永远不
|
||
回头引用它们。
|
||
- 机械化校验：`script/check-core-cohesion.ts` 的 C-1 扫描——HARD 模式
|
||
（实例机密/专有地址）对全部 core 生效；SOFT 模式（实例路径/工具名）
|
||
对 `core/adapters/**` 豁免、其余 core 文件生效（见「增量采用」）。
|
||
|
||
## 不变量 C-2：迁移保编号
|
||
|
||
- 清单迁移**仅改位置、不改编号**：任何规则 / 技能 / 清单迁入 Core 时，
|
||
其标识符（issue 编号、TD 编号、检查项编号）原样保留。
|
||
- 编号是跨实例的稳定契约；重编号会切断历史追溯链。
|
||
- 映射登记：`core/CORE-MANIFEST.json`（core 路径 ↔ dogfood 路径 ↔ 批次），
|
||
编号保真映射表骨架见 `core/MIGRATION.md`。
|
||
|
||
## SSOT 契约（单一事实源）
|
||
|
||
- **Core = 全量权威副本**：规则、技能、\_shared、清单、模板已全部迁入，
|
||
所有修改先落在 `core/`。**builtin overlay 源权威 = core/**（Increment 6b
|
||
起，`packages/octopus/script/generate-builtin.ts` 的 EMBED_SOURCES 从
|
||
core/ 读取——shipped 默认语料为中立版；仅当实例磁盘无
|
||
`<instance-root>/` 目录时 overlay 才生效）。
|
||
- **`.octopus/` = 消费镜像**：dogfood 实例通过 `script/core-sync.sh` 从
|
||
Core 单向同步（verbatim / verbatimDir 自动逐文件同步；rewritten /
|
||
split 按术语表落地），永不反向。
|
||
- **`examples/` 仅叙事**：只引用 Core，不承载事实源内容。
|
||
- 机械化守护：
|
||
- `script/core-sync.sh` — 单向同步（`--check` 只检不写，CI 用）；
|
||
- `script/check-core-parity.ts` — 逐对比较 manifest 登记的文件内容，
|
||
不一致即报漂移；
|
||
- `script/check-core-cohesion.ts` — manifest 路径存在性 + C-1 扫描；
|
||
- `script/check-dangling-refs.ts` — 双侧路径存在性 + core 内部引用
|
||
完整性（intra-core 悬空检出；`--scope-report` 输出覆盖摘要）；
|
||
- `script/check-scaffold-parity.ts` — scaffold-template twin 逐字节
|
||
校验（schema $id owner token 归一化比较）；
|
||
- `script/delink-core.ts` — 去链接化契约执行（#NNNN 活引用 → [org-internal #NNNN]
|
||
注记；幂等；--check 零剩余才过；Inc 6b 字节锁镜像翻转 rewritten 后无递延）；
|
||
- `script/check-core-p1.ts` — P1 零残留终验（私网 IP / 实例主机名 / 个人
|
||
身份 / 旧 owner token 全树 grep；豁免 id-aliases.json 与历史命名空间
|
||
URL 声明；Inc 6b 起无字节锁递延）；
|
||
- `script/check-schema-ids.ts` — core schemas $id 命名空间/文件名匹配
|
||
- id-aliases 一对一/存在性 + 历史接受集声明在位（完整 guards 表见
|
||
文末「机械化守护（guards）」）。
|
||
|
||
## 发布单元达标（Increment 6a + 6b）
|
||
|
||
- **去链接化契约已执行**：core/** 全树 #NNNN 活引用已注记化
|
||
（[org-internal #NNNN]），delink:core 幂等可重跑，--check 为零剩余门。
|
||
Inc 6b 已解锁 6a 递延的 60 处字节锁镜像引用（翻转 rewritten 后 core 侧
|
||
全量注记化，0 递延）。
|
||
- **P1 零残留终验门**：check:core-p1 扫 core/ 全部文本文件（md/yaml/
|
||
json/ts），命中私网 IP、实例主机名、个人身份、旧 owner token 即 FAIL；
|
||
id-aliases.json（SCH-F401）与 runs-index 历史命名空间声明豁免。
|
||
Inc 6b 已清偿 6a 递延的 2 处旧 owner token 命中（0 递延）。
|
||
- **examples/ 方向性**：组织沉积教学案例（叙事），只引用 Core、不被 Core
|
||
引用（C-1 单向）；不入 manifest、不进 cohesion 扫描面。
|
||
|
||
## 目录语义
|
||
|
||
| 目录 | 语义 |
|
||
| ---------------------- | ------------------------------------------------------- |
|
||
| `core/rules/` | L1 强制规则的 Core 源（14 份已全部迁入，G0–G3） |
|
||
| `core/skills/` | 技能整目录的 Core 源（17 个已全部迁入，G4 verbatimDir） |
|
||
| `core/skills/_shared/` | 技能共享工件（角色 yaml、评审管线文件等，14 份，G4） |
|
||
| `core/checklists/` | 清单（13 份已全部迁入，G4） |
|
||
| `core/templates/` | 模板（dag.md、runs 布局，2 份已全部迁入，G4） |
|
||
| `core/schemas/` | JSON Schema（8 份已迁入，G5；$id 已迁至公共命名空间） |
|
||
| `core/adapters/` | 实例适配层（后端参考实现；SOFT 扫描豁免、HARD 仍生效） |
|
||
|
||
## 增量采用
|
||
|
||
Core 的采用以 `core/CORE-MANIFEST.json` 登记为准——**登记了才算采用**。
|
||
G0–G4 批次已完成全量迁移（14 规则、17 技能整目录、\_shared 14 份、
|
||
13 清单、2 模板）；后续批次按 `core/MIGRATION.md` 的映射表推进。
|
||
|
||
### C-1 扫描的增量形态（设计决策）
|
||
|
||
模式分两级（Increment 3）：
|
||
|
||
- **HARD**（全 core 生效，含 adapters）：实例主机名、内网 IP 段、实例
|
||
配置路径——实例机密与实例专有地址任何 core 文件不得出现。
|
||
- **SOFT**（`core/adapters/**` 豁免）：`.octopus/`、`packages/octopus`、
|
||
MCP 工具名、工作树路径等实例绑定内容——adapter 目录是 Gitea 参考
|
||
实现，允许承载；其余 core 文件不得出现。
|
||
|
||
G0 三份规则是从实例规则**逐字复制**的，规则正文里出现实例路径字样属
|
||
**叙述性引用**，且都在行内代码/围栏内（扫描先剥离，零命中）。
|
||
脚本以 `--strict` 开关预留更严形态：`--strict` 时额外对 verbatim 文件
|
||
按全模式集扫描（剥离语义同前）。默认扫描面 = core 下全部 `.md` 文件
|
||
（含 adapters，adapters 只查 HARD）。扫描匹配前先剥离行内代码 span
|
||
（反引号内文字）与围栏代码块——反引号内的是定义性提及（如本文件对
|
||
C-1 模式列表的描述），不是活引用。
|
||
|
||
### manifest 语义（sync 字段）
|
||
|
||
| sync 值 | 语义 | parity 校验 | core-sync 行为 |
|
||
| ------------- | --------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------ |
|
||
| `verbatim` | 逐字复制 | 字节比较 | Core → dogfood 自动 `cp` |
|
||
| `verbatimDir` | 整目录逐字复制（目录级行，core 路径以 `/` 结尾） | 递归文件集一致（排除 `.gitkeep`）+ 逐文件字节比较 | Core → dogfood 逐文件同步 |
|
||
| `rewritten` | 接口中立化改写 | 双侧存在 + core 侧 HARD+SOFT 扫描 | `managed-by: rewrite (no auto-sync)` |
|
||
| `split` | adapter 拆分上提（页名/寻址语义已上提 Core 契约，API 形态留 adapter） | 双侧存在 + core 侧 HARD 扫描（SOFT 豁免） | `managed-by: split (no auto-sync)` |
|
||
| `core-only` | Core 原生契约，无 dogfood 对应（`dogfood: null`） | core 存在 + HARD+SOFT 扫描，无 dogfood 检查 | `managed-by: core-only` |
|
||
|
||
`deferHard: true`（历史字段，**Increment 6a 已全数清零**）：曾标记暂含实例
|
||
表述的行；6a 已将全部 27 行中立化改写为 rewritten 并删除该键。现
|
||
manifest 中不存在 deferHard 行，cohesion `--strict` 的 deferred 计数为 0。
|