# 恒天项目 KB 整改 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

**Goal:** 将恒天项目知识库改造成可路由、可追溯、可验收的项目支持 KB，并初始化独立 BOS Issue Ledger。

**Architecture:** 根 AGENTS.md 作为轻量 dispatcher，项目运行规约承载通用铁律。单一项目 KB 拆分为按需加载的项目 KB 目录，兼容入口只重定向。独立 Ledger 以单独 Git 仓库和 Registry 坐标存在，不自动迁移现有问题摘要。

**Tech Stack:** Markdown、CSV、PowerShell、Git、GitLab CLI、BOS Issue Ledger Python 脚本。

---

## 文件结构

| 文件 | 责任 |
| --- | --- |
| AGENTS.md | 项目 Agent 的强制加载顺序、三层路由、Ledger 入口和安全摘要。 |
| PROMPT_恒天项目运行规约.md | 请求分类、来源、生产确认、诊断、双输出、集成、冲突与 Ledger 回写的可执行规则。 |
| KB_恒天奥特发系统.md | 向后兼容入口，只指向新项目 KB 导航。 |
| KB_恒天奥特发系统/00 至 09 文件 | 拆分后的项目导航、事实、决策、问题、集成、测试、映射和来源索引。 |
| KB_恒天奥特发系统/acceptance_tests.md | 28 个可执行验收题。 |
| KB_恒天奥特发系统/ai_answer_sheet.md | 双 AI 回答与来源记录表。 |
| KB_恒天奥特发系统/scoring_matrix.csv | 题目、证据、双 AI 结果与一致性记录。 |
| README.md | 安全的仓库入口与导航。 |
| 独立 hengtian-issues-ops 仓库 | BOS Ledger 的 list-config、Issue 对象和投影视图；与项目 KB 仓库分离。 |

### Task 1: 建立项目 KB 的目录化结构

**Files:**
- Create: KB_恒天奥特发系统/00_项目导航.md
- Create: KB_恒天奥特发系统/01_项目概况与范围.md
- Create: KB_恒天奥特发系统/02_组织与主数据_真实值.md
- Create: KB_恒天奥特发系统/03_蓝图决策_FICO.md
- Create: KB_恒天奥特发系统/04_蓝图决策_业务与集成.md
- Create: KB_恒天奥特发系统/05_未决问题摘要.md
- Create: KB_恒天奥特发系统/06_集成约定.md
- Create: KB_恒天奥特发系统/07_测试与上线问题.md
- Create: KB_恒天奥特发系统/08_项目范围与Scope_Item参考映射.md
- Create: KB_恒天奥特发系统/08_SC操作索引.md
- Create: KB_恒天奥特发系统/09_来源与证据索引.md
- Modify: KB_恒天奥特发系统.md

- [ ] **Step 1: 记录原始事实校验基线**

Run:

    $source = Get-Content -Raw -LiteralPath 'KB_恒天奥特发系统.md' -Encoding utf8
    @('项目概况','公司代码结构','蓝图决策记录','未决问题清单','集成约定','测试记录','Scope Item 参考映射','项目 KB 使用说明') |
      ForEach-Object { if ($source -notmatch [regex]::Escape($_)) { throw "缺失原始章节：$_" } }

Expected: exits 0.

- [ ] **Step 2: 创建拆分后的项目事实文件**

按原单文件章节拆分，所有项目专属值原样保留：

| 原章节 | 新文件 |
| --- | --- |
| 项目概况、系统环境、范围、交付与第三方总体规则 | 01_项目概况与范围.md |
| 公司代码结构和控制范围 | 02_组织与主数据_真实值.md |
| FICO 决策 | 03_蓝图决策_FICO.md |
| MM、SD、PP、PS、QM、迁移、第三方决策 | 04_蓝图决策_业务与集成.md |
| 未决问题清单 | 05_未决问题摘要.md |
| 集成约定 | 06_集成约定.md |
| 测试脚本引用与已知测试问题 | 07_测试与上线问题.md |
| Scope Item、E2E 与三层关系 | 08_项目范围与Scope_Item参考映射.md |
| SC 标准操作入口 | 08_SC操作索引.md |
| 原附录源材料清单和仓库内状态 | 09_来源与证据索引.md |

每个文件必须有 H1、来源状态和指向 00_项目导航.md 的入口链接。

- [ ] **Step 3: 创建项目导航**

00_项目导航.md 必须包含以下可直接使用内容：

    ## 使用目的与受众
    供项目经理、实施顾问和经授权的支持人员查询项目真实值、蓝图、项目特例、范围、集成和问题摘要。

    ## 三层路由
    项目 KB → KB_SC → KB_SA。
    项目事实优先；标准操作转 KB_SC；产品能力、Scope Item 和版本边界转 KB_SA。

    ## 冲突与证据
    冲突、合规、数据安全或生产写操作立即停止并请求人工确认。没有可验证来源时明确写“KB未覆盖”或“我不确定”。

导航表必须列出每份项目文件的用途、来源状态和更新触发。

- [ ] **Step 4: 把原单文件改为兼容入口**

Replace its content with:

    # KB_恒天奥特发系统 — 兼容入口

    项目 KB 已拆分为按需检索文件。请从 [项目导航](../../../KB_恒天奥特发系统/00_项目导航.md) 开始；不要同时加载本入口和全部项目文件。

- [ ] **Step 5: 检查拆分结构和事实存在性**

Run:

    $expected = @(
      '00_项目导航.md','01_项目概况与范围.md','02_组织与主数据_真实值.md',
      '03_蓝图决策_FICO.md','04_蓝图决策_业务与集成.md','05_未决问题摘要.md',
      '06_集成约定.md','07_测试与上线问题.md','08_项目范围与Scope_Item参考映射.md','08_SC操作索引.md',
      '09_来源与证据索引.md'
    )
    $expected | ForEach-Object {
      if (-not (Test-Path -LiteralPath (Join-Path 'KB_恒天奥特发系统' $_))) { throw "缺失：$_" }
    }
    rg -n '蓝图决策|未决问题|集成约定|测试问题|Scope Item' KB_恒天奥特发系统 -g '*.md'

Expected: all ten files exist and the search returns split-file evidence.

### Task 2: 写入根入口与项目运行规约

**Files:**
- Create: AGENTS.md
- Create: PROMPT_恒天项目运行规约.md
- Modify: README.md

- [ ] **Step 1: 创建根 AGENTS.md dispatcher**

AGENTS.md must declare:

    ## System Prompt（每次对话开始时加载，顺序不可颠倒）
    1. KB_恒天奥特发系统/00_项目导航.md
    2. PROMPT_恒天项目运行规约.md
    3. KB_SC/PROMPT_SC_Agent_Runtime_v2.1.md
    4. KB_SA/SYSTEM_PROMPT_Agent1_v1.67.md

    ## KB 三层路由
    KB_恒天奥特发系统/ → KB_SC/ → KB_SA/

Add a BOS Ledger block with verified list ID hengtian-ops-26 and a neutral Registry path convention. Do not add reference-project customer names, owner names, Issue ranges or system URLs.

- [ ] **Step 2: 创建项目运行规约**

PROMPT_恒天项目运行规约.md must have sections for:

    元数据、Cloud Public Edition 拦截、请求 A/B/C/D/E 分类、场景确认、
    来源先行、D/T/P 生产确认、诊断四步、边界分流、集成触点、
    占位值、自查与冲突、固定诊断模板、客户双分区、禁用表述、
    Session 到独立 Issue Ledger 的确认后回写。

Where no target fact exists, use only:

    <项目负责人>
    <角色/团队>
    <Issue Ledger路径>

- [ ] **Step 3: 更新 README**

Link AGENTS.md, project navigation, SA/SC navigation, runtime prompt and independent Ledger path convention. Do not repeat true values or external URLs.

- [ ] **Step 4: 检查运行控制**

Run:

    $files = @('AGENTS.md','PROMPT_恒天项目运行规约.md','README.md')
    $terms = @('A-知识查询','D/T/P','给客户的信息','给顾问的内部分析','Issue Ledger','KB未覆盖','Fiori','占位值','冲突')
    foreach ($term in $terms) {
      if (-not (rg -l --fixed-strings $term $files)) { throw "缺少运行控制：$term" }
    }

Expected: exits 0.

### Task 3: 补齐来源索引和验收资产

**Files:**
- Create: KB_恒天奥特发系统/acceptance_tests.md
- Create: KB_恒天奥特发系统/ai_answer_sheet.md
- Create: KB_恒天奥特发系统/scoring_matrix.csv
- Modify: KB_恒天奥特发系统/09_来源与证据索引.md

- [ ] **Step 1: 写入来源索引状态**

Use this table and do not invent any link, hash, date or owner:

| 来源类别 | 已知文件或模式 | 用途 | 仓库内状态 | 后续动作 |
| --- | --- | --- | --- | --- |
| 合同/SOW | 原项目附录中列出的文件 | 项目范围 | 未随仓库提交 | 补受控存储链接与章节锚点 |
| 会议纪要 | 原项目附录的会议纪要集合 | 蓝图决策 | 未随仓库提交 | 补会议编号、日期、页码 |
| 测试脚本 | 原项目附录列出的测试脚本 | 测试记录 | 未随仓库提交 | 补受控链接和执行结果 |

- [ ] **Step 2: 创建验收题库与答案表**

Create 28 tests covering true values, blueprints, project exceptions, SA/SC routing, Cloud interception, customer dual output, diagnosis, production confirmation, integration boundaries, placeholder values, Ledger writeback and prohibited wording. Each test must have expected evidence. The answer sheet must contain AI-1 answer/source, AI-2 answer/source and difference columns.

- [ ] **Step 3: 创建 CSV 评分矩阵**

Use this header:

    ID,Category,RequiredPoints,Evidence,AI1Pass,AI2Pass,Consistent,Finding

Add T-01 through T-28 with matching categories and empty result cells.

- [ ] **Step 4: 检查验收资产**

Run:

    $required = @(
      'KB_恒天奥特发系统/acceptance_tests.md',
      'KB_恒天奥特发系统/ai_answer_sheet.md',
      'KB_恒天奥特发系统/scoring_matrix.csv'
    )
    $required | ForEach-Object { if (-not (Test-Path -LiteralPath $_)) { throw "缺失：$_" } }
    Import-Csv 'KB_恒天奥特发系统/scoring_matrix.csv' | Measure-Object | Select-Object -ExpandProperty Count

Expected: exits 0 and outputs 28.

### Task 4: 初始化独立 BOS Issue Ledger

**Files:**
- Create outside project KB repository: private hengtian-issues-ops GitLab repository containing hengtian-ops-26/list-config.md.
- Modify after remote verification: AGENTS.md.
- Delete after remote verification: hengtian-ops-26/list-config.md.

- [ ] **Step 1: 验证 GitLab 创建认证**

Run:

    glab auth status --hostname 118.31.18.126:9001

Expected: authenticated account. Current observed state is unauthenticated, so stop here and request glab auth login --hostname 118.31.18.126:9001. Never create a fake remote URL.

- [ ] **Step 2: 创建独立私有 Ledger 仓库**

After authentication succeeds, run:

    glab repo create bosAi/hengtian-issues-ops --private --defaultBranch master --remote origin

Expected: new remote repository returned and origin configured in its local Ledger clone.

- [ ] **Step 3: 初始化配置而不创建 Issue**

Copy approved hengtian-ops-26/list-config.md into the Ledger repository. Change only:

    repo: git@118.31.18.126:bosAi/hengtian-issues-ops.git
    version: 3

Replace title status “草案，待 SA 审批” with “已批准配置”. Retain existing checklists and migration record. Do not create issues/*.md.

- [ ] **Step 4: 注册并切换 Ledger**

The existing Registry already contains hengtian-ops-26 and points it to the project KB repository. Replace only that entry with:

    list_id: hengtian-ops-26
    display_name: hengtian问题清单
    project: hengtian项目
    customer: hengtian
    repo: git@118.31.18.126:bosAi/hengtian-issues-ops.git
    branch: master
    mode: standalone
    subdir: hengtian-ops-26
    issue_prefix: ISS
    owner: SA
    status: active

Then run:

    python "$env:USERPROFILE\.codex\skills\bos-issue-ledger\scripts\switch_ledger.py" --list-id hengtian-ops-26
    python "$env:USERPROFILE\.codex\skills\bos-issue-ledger\scripts\list_issues.py" "$KB" --dashboard

Expected: list resolves, dashboard reports zero issues, and no Issue object is created.

- [ ] **Step 5: 验证远端并清理旧配置**

Run:

    $ledgerRoot = "$env:USERPROFILE\.codex\skills\bos-issue-ledger\ledgers\hengtian-issues-ops"
    git -C $ledgerRoot ls-remote --heads origin master
    Test-Path -LiteralPath "$ledgerRoot\hengtian-ops-26\list-config.md"
    Get-ChildItem -LiteralPath "$ledgerRoot\hengtian-ops-26\issues" -File -ErrorAction SilentlyContinue

Expected: master exists, configuration exists and issues contains zero files. Only after these checks pass, remove copied hengtian-ops-26/list-config.md from project KB repository and update AGENTS.md with the final Ledger coordinate.

### Task 5: 整体验证和交付

**Files:**
- Verify: all Task 1–4 files.

- [ ] **Step 1: 检查项目 KB 链接与标题**

Run:

    rg -n '\]\(([^)]+)\)' README.md AGENTS.md KB_恒天奥特发系统.md KB_恒天奥特发系统 -g '*.md'
    rg -n '^#|^##|^###' AGENTS.md PROMPT_恒天项目运行规约.md KB_恒天奥特发系统 -g '*.md'

Expected: no link points to an absent in-repository file and each created Markdown has one H1.

- [ ] **Step 2: 检查参考项目私有值隔离**

Run:

    rg -n '康诺医疗|s0626|KB_康诺|ISS-KN-|张宝龙' AGENTS.md PROMPT_恒天项目运行规约.md KB_恒天奥特发系统 README.md

Expected: no matches.

- [ ] **Step 3: 检查变更范围**

Run:

    git status --short
    git diff --check

Expected: only planned KB files, docs/superpowers artifacts, README, AGENTS and runtime prompt are modified; no whitespace errors.

- [ ] **Step 4: 如实报告 Ledger 状态**

If Task 4 is blocked by authentication, report repository-local remediation as complete and Ledger external provisioning as blocked. Do not report the P1 as closed until remote Ledger and Registry verification pass.
