8.1 KiB
8.1 KiB
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、 后端绑定内容（REST 端点、工作树路径等）——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。