openxiangda-skill-kit 2.0.0-alpha.99 → 2.0.0

package/skills/openxiangda-v2/references/application-foundation.md

@@ -0,0 +1,162 @@
+# 业务模块与标准 CRUD 基础
+
+这是 2026-09-05 平台重构的首批能力。数据存储、页面选择和角色授权独立定义，仍编译到平台现有 Data API、Surface 和权限引擎。
+
+## 从业务任务到模块
+
+先确定用户要完成的任务，再选择页面。辅助数据模型不需要独立页面；复杂任务页可组合多个模型。简单应用显式选择标准 CRUD 即可。
+
+```ts
+// modules/records/models.ts
+import { defineDataModel } from 'openxiangda/config';
+
+export const records = defineDataModel({
+  code: 'records', name: '记录',
+  fields: [
+    { code: 'title', label: '名称', type: 'text.short', required: true },
+    { code: 'enabled', label: '启用', type: 'boolean' },
+    { code: 'source_key', label: '来源标识', type: 'text.short', hidden: true },
+  ],
+});
+```
+
+```ts
+// modules/records/index.ts
+import { defineApplicationModule, defineResourceForm, defineResourceList } from 'openxiangda/config';
+import { records } from './models';
+
+export const recordsModule = defineApplicationModule({
+  code: 'records', models: [records],
+  crud: [{
+    model: records.code,
+    list: defineResourceList(records, { fields: ['title', 'enabled'], filterFields: ['enabled'] }),
+    form: defineResourceForm(records, { fields: ['title', 'enabled'] }),
+  }],
+});
+```
+
+不写 `crud` 时仅注册数据模型；`crud: [{ model: records.code }]` 使用标准页面默认字段。列表默认列、表单、详情的字段选择均保持给定顺序。一个模型可以声明多套命名视图，各自配置字段、分组和操作入口，共用同一份数据和权限。
+
+```ts
+// openxiangda.config.ts
+import { defineOpenXiangdaApp, resourceRoleCapabilities } from 'openxiangda/config';
+import { recordsModule } from './modules/records';
+
+const appCode = 'my-app';
+export default defineOpenXiangdaApp({
+  app: { code: appCode, name: '我的应用' },
+  modules: [recordsModule],
+  frontend: { admin: { navigation: [] } },
+  authz: { capabilities: [], roles: [
+    { code: 'reader', name: '查阅成员', capabilities: resourceRoleCapabilities(appCode, 'records', 'read') },
+    { code: 'manager', name: '管理成员', capabilities: resourceRoleCapabilities(appCode, 'records', 'manage') },
+  ] },
+});
+```
+
+菜单单独规划；可使用现有 `suggestAdminNavigation` 提案后选择需要的条目。`read` 仅授予查看，`manage` 明确包含增删改查，也可传 `['read', 'create']`。页面生成不会改变角色权限。
+
+## 同一模型的多套页面
+
+例如简要登记只填写名称，完整管理填写名称和启用状态：
+
+```ts
+crud: [
+  {
+    model: records.code, code: 'quick', name: '简要登记',
+    list: defineResourceList(records, { fields: ['title'] }),
+    form: defineResourceForm(records, { fields: ['title'] }),
+    detail: defineResourceForm(records, { fields: ['title'] }),
+    sections: [{ title: '登记信息', fields: ['title'] }],
+    generated: { delete: false },
+  },
+  {
+    model: records.code, code: 'complete', name: '完整管理',
+    form: defineResourceForm(records, { fields: ['title', 'enabled'] }),
+    sections: [{ title: '基本信息', fields: ['title'] }, { title: '管理设置', fields: ['enabled'] }],
+  },
+]
+```
+
+使用 `adminResourcePage('records', { viewCode: 'quick' })` 绑定菜单。平台生成
+`/admin/resources/records/views/quick`、`/new`、`/:id`、`/:id/edit` 和对应移动地址；
+抽屉全屏、新开页面及提交后的返回地址都保留当前视图。每个模型最多 20 个命名视图，
+`code` 必须唯一且为小写短横线格式。省略 `code` 的一套视图保留原地址；只声明命名视图时不额外生成默认页面。
+
+命名新建表单必须包含模型中可写的必填字段。仅用于局部编辑的表单可声明
+`generated: { create: false }`。`mobile: { enabled: false }` 关闭该视图的移动页面。
+视图不能重定义字段类型、权限或写入归属，也不能用隐藏字段代替授权。
+个人显示列设置和草稿按视图隔离；列设置仍可主动选取允许展示的其它字段。
+此能力要求匹配的服务端校验和 `AddFormDraftViewScope` SQL 迁移。
+
+## 字段与控件
+
+标准 PC 管理页沿用一行工具栏和可折叠菜单。新增、编辑默认在抽屉中进行，保存后刷新原列表并保留当前筛选和页码；也可使用已有整页录入地址。筛选、显示列、排序按需打开。默认列来自选定的业务字段，创建、更新时间需主动选择。列选择、拖动顺序与冻结立即预览，点击工具栏“保存”后记住个人配置；多排序按规则顺序生效。
+
+在 `crud` 视图上声明共享的表单/详情分组，不向存储模型添加布局：
+
+```ts
+crud: [{
+  model: records.code,
+  form: defineResourceForm(records, { fields: ['title', 'enabled'] }),
+  sections: [
+    { title: '基本信息', fields: ['title'] },
+    { title: '使用设置', fields: ['enabled'] },
+  ],
+}]
+```
+
+分组只标记字段所属区域；表单/详情的 `fields` 仍决定展示集合及顺序，不会追加组内其它字段。普通小表单可省略分组。PC 每行最多两个普通字段，长文本、附件等复杂字段占整行；移动端使用单列。失败时保留输入并显示错误，未保存退出时提示确认。筛选可嵌套“满足全部／满足任一”，按字段类型提供运算符；查询、分页和导出使用同一条件树及多排序。批量扩展动作声明 `requiresSelection: true`，选择记录后才显示。
+
+`hidden` 仅控制展示。`system` 表示由服务端维护，默认隐藏；业务需要展示的流水号、状态可显式 `hidden: false`。隐藏不会撤销 Data API 的读写授权；授权仍用现有字段 `access` 与行策略。普通必填字段不能从可新增表单中漏掉；内部必填值应有清晰的服务端赋值责任，不能靠隐藏字段绕过数据约束。
+
+业务组件优先使用 `openxiangda/field-kit`，PC 补充使用 `antd`，移动端使用 `openxiangda/mobile` 封装的 Ant Design Mobile 控件。移动控件已覆盖文本、长文本、数字、布尔、静态选项、日期时间，以及人员／部门目录、动态资源引用和级联选择。选择弹层支持逐层浏览、搜索、翻页和已选项管理，点击确定才写回表单，关闭放弃本次修改。附件、图片、地址、子表和签名已提供移动交互，富文本在手机使用纯文本编辑并保留未修改 HTML；能力边界见[字段组件](field-components.md)。共享值协议和表单控制器，不共享桌面弹层交互。
+
+```tsx
+import { MobileSurface, Input, Button } from 'openxiangda/mobile';
+import 'openxiangda/mobile/styles.css';
+
+// 在移动页面的最外层使用；标准 MobileSurfaceFieldControl 自带字段样式范围。
+<MobileSurface>
+  <Input value={title} onChange={setTitle} aria-label="名称" />
+  <Button color="primary" onClick={save}>保存</Button>
+</MobileSurface>
+```
+
+平台按需加载移动组件，并在构建时限定上游基础样式的作用范围。此入口的 `Popup`、`Picker`、`DatePicker` 默认保留在当前页面中，保留组件样式作用范围。已有 `openxiangda/react/styles.css` 包含移动字段样式，不必重复导入。不要直接引入 `antd-mobile` 根入口，它会重置全页字体和链接。平台统一使用组件库默认外观，不再提供配色配置或外观偏好。
+
+`openxiangda check` 检查应用前端 `src/` 中的原生录入元素。移动入口使用 `src/mobile/`、`Mobile*.tsx` 或 `*.mobile.tsx`，并检查其本地静态依赖；这是明确的源码约定，不是运行时授权或对动态代码的安全证明。平台组件内部的原生 DOM 不受应用规则限制。
+
+## 开发与验收
+
+普通 CRUD 可以省略 `backend`、`platform` 配置，`pnpm dev` 通过现有 connected development 连接平台。默认模板不包含后端源码；显式启用或声明需要应用代码执行的后端能力后，`pnpm openxiangda check` 或 `pnpm dev` 按需初始化源码与依赖，再启动 Nest。标准流程定义和激活由平台执行，不要求应用后端。
+
+`appspec/app.md` 维护总纲和设计索引。新应用按[产品设计](product-design.md)完成本期详细需求、任务旅程、逐页交互、权限与架构及实际确认基线，再制定实施计划；已有小变更只修订受影响材料。业务角色与权限由用户确认，技术 schema、接口和存储计划由平台产出；按业务规模拆分能力记录。
+
+先读取 MCP 契约索引，再调用 `contract_describe` 并传入 `{ "selector": "permissions" }`，读取
+`data.selection.permissionReview`。该产物使用 `openxiangda.permission-review/v2`，
+`authority` 为 `declaration-projection`，并始终保留
+`runtimeAuthorizationRequired: true`；`configDigest`、`contractDigest` 和
+自身 `digest` 对应当前编译结果，便于在 appspec 中关联审核证据。
+
+角色的 `capabilityCodes` 是编译后声明的能力集合，可通过能力代码关联页面、
+资源操作和字段要求。运行时仍按当前用户的应用角色并集授权；
+`deniedCapabilities` 只在编译时扣除该角色的 grant，不是跨角色的全局拒绝。
+命名视图通过 `resourceCode` / `viewCode` 引用同一资源，字段策略只保存一次。
+空字段策略显示为 `deny`，隐藏字段只代表展示选择。原始行谓词、scope 来源和
+流程参与人绑定保留为待运行时求值的条件；静态能力匹配不代表真实请求允许。
+该产物供审核使用，不写入角色、授权或另一份审批状态。
+
+单元测试覆盖复杂业务规则、值转换和权限边界；接口测试覆盖存储、事务与策略；浏览器验收必须实际点击 PC/移动端的新增、选择、清空、保存、编辑和回显，并检查页面错误。组件模拟测试不等于已在远端真实业务环境验收。
+
+## Alpha 应用迁移
+
+依赖旧版“读权限自动附带写权限”的角色必须改成明确的 `manage` 或操作列表。原有 `data.resources` 可继续作为同一编译器的低层输入，按模块逐步拆分；不增加第二套资源存储。新增 `surface.fields.*.hidden` 与 `surface.list.fieldOrder` 需要配套平台版本，发布时必须固定匹配的服务端与工具链提交。
+
+## 标准表单暂存
+
+标准表单底部为“暂存 / 提交”。暂存允许必填项未完成，不写业务表、不启动流程；草稿箱可继续编辑或删除。草稿由平台当前用户、应用、环境和资源隔离，最多 20 份、90 天未更新过期。恢复编辑草稿保留原记录版本，提交仍检查冲突；正式提交与消耗草稿在同一 Data API 事务内完成。
+
+PC 抽屉提供“全屏 / 新开页面 / 关闭”。全屏保留当前表单；新开页面先暂存，再通过草稿 ID 恢复，内容不放入 URL。移动录入使用平台移动字段的分组行式布局、简单标题和底部操作，不放“返回列表”或桌面输入控件；草稿箱和恢复确认使用底部弹层。
+
+自定义表单可从 `openxiangda/react` 使用 `createResourceFormDraftClient(resourceCode, mode, recordId?, viewCode?)`，提供 `list/save/remove/submit`。命名视图只能恢复和提交属于当前视图的草稿；所有视图仍共用每人每个模型 20 份的上限。`save` 使用草稿 ID、expectedRevision 和可编辑字段值；`submit` 消费现有 DataTransactionOperation，不另建 CRUD 后端。此能力需要平台的 authenticated-form-drafts SQL 迁移及对应服务端版本，平台未升级时界面会明确显示暂存失败并保留输入。

package/skills/openxiangda-v2/references/appspec.md

@@ -1,67 +1,152 @@
-# AppSpec
+# AppSpec：需求、设计与交付记录
 
-AppSpec 是 OpenXiangda 2.0 应用仓库中的可选业务意图层。它帮助 AI 理解“为什么做、应当表现成
-什么、这次改变什么”，但不复制 `openxiangda.config.ts`、编译合同、代码、测试或部署状态，也
-不是发布门禁。
+AppSpec 是默认开发流程中的业务记录，保存在应用 Git 仓库。AI 负责整理需求、分析架构和性能、维护记录；产品经理主要说明目标与业务规则。当前总纲、实现声明、实际验收和平台部署各有自己的事实来源，不能互相替代。
 
-AppSpec 只使用 2.0 的 `appspec/`、文档 schema v1 与 context v2。绝不读取、识别、导入或迁移
-1.x 的 `openspec/`、SDD、表单、页面、函数和发布材料。
+## 资料结构
 
-## 何时读取
+```text
+appspec/
+  app.md                 # 当前有效目标、规则、架构、页面、权限、容量
+  product/               # 来源、范围与 PRD
+  experience/            # 旅程、逐页交互
+  design/                # 视觉、权限、架构与原型引用
+  reviews/               # 实际确认与设计基线
+  capabilities/          # 复杂后再按业务能力拆分，不要求小应用创建
+  changes/active/        # 本轮需求、设计、任务、验收与交接
+  changes/history/       # 完成后的变更，按年保存
+  decisions/             # 需要长期引用的架构决定
+  verification/          # 绑定测试版本的业务验收报告
+```
 
-- 工作区存在 `appspec/` 时，在分析需求或修改行为前运行 `pnpm openxiangda spec context --json`，先读取
-  有界索引。
-- 从索引选择相关变更、能力、ADR 或历史变更 ID，再运行例如
-  `pnpm openxiangda spec context booking-window --json` 读取正文。
-- AI-native 客户端可读取 `openxiangda://workspace/appspec` 或调用 `appspec_context`。
-- 默认不加载全部正文；历史变更只在追查原因时用稳定 ID 按需读取。
+新应用按[产品设计](product-design.md)完成本期详细材料和设计基线；既有变更只更新受影响范围，文案和无行为变化沿用有效基线。业务规则使用 `### REQ-*`，可观察验收使用 `#### AC-*`；ID 稳定，变更引用当前总纲或能力中的规则。声明和生成契约保存模型、字段与接口，AppSpec 不复制 Schema 全集。截图、请求轨迹等证据保留实际文件或 HTTPS 引用，不提交凭据和敏感业务数据。
 
-## 何时维护
+## 从模糊需求到实现
 
-| 风险 | 典型变化 | 最小维护量 |
-| --- | --- | --- |
-| L0 | 重构、格式、无行为变化 | 不创建 ChangeSpec |
-| L1 | 文案、单字段、局部规则 | 一份短 ChangeSpec |
-| L2 | 跨资源、权限、状态变化 | 加正反验收、数据与回滚 |
-| L3 | 身份、迁移、并发、外部副作用 | 加失败/幂等、资源边界和 ADR |
+1. 读取当前总纲、设计索引与相关稳定 ID，分析用户提供资料，区分事实、候选建议、实际确认、延期与冲突。
+2. 主动帮助用户从真实任务发现模块，逐轮少量提问、建议与复述，已确认且未变的决定持续有效。
+3. 完成本期产品、旅程、逐页交互、视觉/原型、权限和架构设计；按角色走查主任务与异常，维护容量预算与可证伪 AC。
+4. ChangeSpec 的 documents 引用一份 review 设计文档；评审关联受评设计的传递引用闭包、实际确认来源和 baselineDigest。具体模板及范围规则见[产品设计](product-design.md#templates)。
+5. readyForImplementation 成立后制定实施计划，关联 REQ、设计、源码和 AC；本轮任务及原有交付章节完整后 readyForTest 成立。
+6. 实施、检查、测试部署、真实角色验收、生产晋级后，更新持续有效规则、实际结果和交接，再归档。
 
-用户没有要求且变更是 L0 时，不要为了“流程完整”创建文档。小应用可以长期只维护 `app.md`。
+`未确认问题` 下的 `- [ ]` 表示正式交付阻断项。非阻断假设另写说明。只有章节、一个 `passed` 标记或 AI 的判断，均不能证明业务验收实际发生。
 
-## 标准操作
+## 命令与阶段边界
 
 ```bash
 pnpm openxiangda spec init
-pnpm openxiangda spec add-capability CAP-BOOKING --title "预约管理" --resources bookings
-pnpm openxiangda spec new booking-window --title "限制可预约时段" --risk L1 \
-  --capabilities CAP-BOOKING --resources bookings
+pnpm openxiangda spec new booking-window --title "限制可预约时段" --risk L2
 pnpm openxiangda spec context booking-window --json
 pnpm openxiangda spec check
-pnpm openxiangda spec close booking-window --current-spec merged \
-  --summary "已通过真实角色验收"
 ```
 
-`spec check` 是用户主动选择的严格检查；普通 `check/dev/deploy` 只给 advisory，不因 AppSpec
-缺失或不完整而失败。
+已有工作区优先用 `spec new` 生成本地记录。访谈尚未创建应用时，可在 `appspec/changes/active/<变更ID>.md` 手工建草稿：front matter 使用 `schema: openxiangda.appspec/change/v1`、与文件名一致的 `id`、`title`、`status: draft`、`currentSpec: pending`、适用的 `risk`，以及 `documents: [实际评审ID]`。不必为整理设计先创建远端应用。
+
+| 阶段或风险 | ChangeSpec 必需正文 |
+| --- | --- |
+| 设计阶段 | 为什么、需求依据、方案与影响、验收、性能与容量预算；引用详细权威材料并说明本轮影响 |
+| 设计就绪后 | 补齐任务与实现；草稿不能冒充已可测试 |
+| L2 / L3 | 另写数据与权限、回滚；引用权限和架构材料，说明适用范围或不适用理由 |
+| L3 | 另写失败、并发与幂等、架构决策；需要长期决定时关联实际 ADR |
+| 关闭前 | 验证与发布、交接，填写实际结果和剩余事项 |
+
+`未确认问题` 单独保留阻断项，设计评审和实施任务按[开工顺序](product-design.md#readiness)分步完成。章节名用于定位缺口，空标题、模板提示和未执行的验收计划均不是完成证据。
+
+有且仅有一个活动变更时自动关联。多个活动变更或引用历史记录时，在本次 Git 提交说明中加入 `AppSpec: booking-window`。格式、无行为重构可引用已有记录，在提交说明写清不改变业务行为的依据，无需制造重复文档；新的行为变化仍要更新相应变更。
+
+| 操作 | 实际要求 |
+| --- | --- |
+| dev、只读分析 | 可以研究和预览，不能把原型当作已完成交付 |
+| 普通 check / check_app | 技术验证照常进行，需求与设计缺口作为单独诊断返回 |
+| spec context | 返回 readyForImplementation、readyForTest、评审摘要与缺口；不自动确认 |
+| spec check | 严格检查当前文档、设计基线、关联变更和测试发布前的完整性 |
+| 测试 deploy / deploy_app | 总纲、设计、需求依据、性能预算、AC 计划完整；尚不要求线上业务验收报告 |
+| 生产晋级 | 读取指定成功测试运行的同一制品，并核对绑定该版本的实际验收报告 |
+| spec close | 当前长期规则已回写，“验证与发布”和“交接”有实际结论；未发布、取消和未覆盖项明确说明 |
+
+发布前提交、推送并合入远端默认主分支。测试部署之后的验收报告是后续提交，生产仍复用原测试包，不因主线新增报告而重新构建。参见[发布与恢复](delivery.md)。
+
+## 测试版本的验收报告
+
+按实际观察建立 `appspec/verification/<测试运行ID>.json`。以下仅展示格式，示例数值和结果不能作为真实证据；报告必须覆盖测试版本 AC 计划，失败和未测场景不能冒充通过。
+
+```json
+{
+  "schemaVersion": "openxiangda.business-verification/v1",
+  "appCode": "booking-app",
+  "changeId": "booking-window",
+  "sourceDeploymentId": "实际测试运行ID",
+  "packageDigest": "实际包的64位SHA256",
+  "recordedAt": "实际记录时间ISO8601",
+  "scenarios": [
+    {
+      "id": "AC-BOOKING-001",
+      "status": "passed",
+      "actor": "实际测试身份及角色",
+      "observation": "实际操作、数据条件和观察到的结果",
+      "evidence": [".openxiangda/evidence/booking-001.png"]
+    }
+  ],
+  "performance": [
+    {
+      "scenario": "实际测量的页面或接口链路",
+      "sample": "测试环境、数据量、样本次数与测量口径",
+      "targetMs": 2000,
+      "observedMs": 450,
+      "evidence": [".openxiangda/evidence/performance.json"]
+    }
+  ]
+}
+```
+
+本地证据路径必须位于工作区内且文件存在；长期报告也可引用 HTTPS 证据。工具核对引用格式、版本绑定、场景覆盖与数值，不替代对截图、业务含义或外部证据真实性的评估。授权角色成功和禁止角色拒绝分别验证；支持范围之外的渠道在需求范围与未覆盖清单中明确说明。
+
+```bash
+pnpm openxiangda spec verify --deployment <测试运行ID>
+# 报告也可显式指定；生产晋级按运行 ID 读取默认路径
+pnpm openxiangda spec verify --deployment <测试运行ID> --evidence appspec/verification/<测试运行ID>.json
+pnpm openxiangda spec close booking-window --current-spec merged --summary "实际完成情况与剩余事项"
+```
+
+MCP `appspec_verify` 读取同一报告与运行事实。`spec verify` 根据当前关联需求核对；生产晋级另外从测试源码提交读取原计划，因此主线后续需求不能冒充旧版本已测内容。不得伪造用户确认、测试身份、执行结果或部署成功。官方工具的记录门槛不代表平台所有直接接口都强制执行了同一业务流程。
+
+## 新任务找回上下文
+
+### 架构决定的编号与创建
+
+需要长期引用的决定写入 `appspec/decisions/` 下的 Markdown。ADR 的 `id` 格式是 `ADR-` 加**恰好四位数字**，可选 `-` 分隔的大写字母或数字后缀，例如 `ADR-0001`、`ADR-0001-DATA-OWNER`；`ADR-001` 不合法。文件名建议与 ID 一致，引用使用元数据中的 ID。当前没有独立的 ADR 创建命令，可以手工创建，随后用 `spec context <ID>` 和 `spec check` 核对。
+
+以下是 `appspec/decisions/ADR-0001.md` 的提议示例；它不表示已经确认或可以发布：
+
+```markdown
+---
+schema: openxiangda.appspec/decision/v1
+id: ADR-0001
+title: 业务数据的权威来源
+status: proposed
+---
+
+# 业务数据的权威来源
+
+## 问题与方案
+
+业务记录由平台 Data API 持有，应用按当前用户权限读取；前端不另建持久业务数据库。
+
+## 影响与验证
+
+关联查询使用平台字段来源，验收时分别核对允许与禁止角色的真实读取结果。
+
+## 未确认问题
+
+- [ ] 确认本期是否存在需要独立后端事务的业务不变量。
+```
 
-新 ChangeSpec 的 `currentSpec` 固定从 `pending` 开始。关闭前先把长期有效结果合入 `app.md` 或相关
-CapabilitySpec，再由用户确认 `merged`；不改变长期规格时由用户确认 `not-applicable`。AI 可以列出
-未合入差异，但不能自行选择这两个值。稳定 REQ/AC 未进入当前规格、L2/L3 必需章节为空或保留默认
-占位内容时，`spec close` 不移动文件。
+ADR 状态支持 `proposed`、`accepted`、`superseded`、`rejected`；按真实决定更新，不为通过检查直接填 `accepted`。可选元数据为 `date`、`deciders`、`supersedes`、`documents`；确认依据和方案取舍写正文。变更用 `decisions: [ADR-0001]` 关联，设计材料也可用 `documents: [ADR-0001]` 引用。修正已有编号时同步相关引用并保留 Git 历史，不删除旧决定来规避检查。
 
-## 写作边界
+### 按 ID 读取
 
-- `app.md` 记录长期目标、角色、范围、术语和跨能力约束。
-- `capabilities/CAP-*.md` 记录当前有效需求，使用稳定 `REQ-*` 和可证伪 `AC-*`。
-- `changes/active/*.md` 只记录本次 delta、风险、影响范围与验收；关闭前把仍有效的结论合入能力规格，
-  并由用户确认 `currentSpec`。
-- `decisions/ADR-*.md` 只用于架构显著决定，不为普通小改创建。
-- 引用真实 2.0 resource/action code，不抄字段定义和权限矩阵的机器事实。
-- AI 可以创建 `draft`、指出未确认问题和建议更新，不能自行把需求标记为 `confirmed`。
-- 不因 AppSpec 与实现冲突就静默修改其中一方；明确指出冲突，由用户决定业务意图，技术事实以实时
-  编译合同为准。
+`context` / `workspace_context` 默认返回总纲、相关变更索引、阶段缺口和下一步。`spec context` / `appspec_context` 的 context v4 默认只返回总纲正文及有界索引，按稳定 ID 加载相关能力、变更、ADR 和 DES-* 设计正文及 documents 传递引用。product/experience/design/reviews 的单层 Markdown 也进入当前资料与原测试提交读取；非 Markdown 原型只引用不执行。当前资料最多 128 文件、2 MiB，正文上下文最多 256 KiB，超出时明确诊断。
 
-## 可迁移程度
+历史与当前资料独立预算，每页 50 条，使用 `--history-offset 50` 或 MCP `historyOffset` 翻页。历史索引仅读取头部，稳定历史 ID 可直接读取页外正文；归档增加不会挤掉当前资料。索引读取上限为 256 个年份目录、10 万个记录名和 5 秒，达到预算给出提示，文件不会删除。`workspaceDigest` 对应当前资料与实时契约，分页不改变它；`selectionDigest` 对应选中的具体正文与契约。
 
-完整 AppSpec 能显著提高另一个新项目复现业务逻辑的概率，但最终文档本身不等于可执行应用。
-需要接近原应用时，应同时提供 AppSpec、`openxiangda.config.ts`、必要自定义动作、测试和外部接口
-合同；历史 ChangeSpec 不是必需输入。
+当前仓库规格不等于生产已上线功能。环境使用哪个版本从平台读取；历史用于解释演进原因，后续实现优先遵循当前有效规则。旧 alpha 记录没有设计评审时不会自动升级成已确认；补齐真实设计和评审后重新测试发布。旧 2.0 应用升级后补齐实际记录，不导入 1.x SDD，也不自动生成虚假确认或验收。