@shundoo-ai/dsh-cosmic 1.0.17 → 1.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shundoo-ai/dsh-cosmic",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "苍穹助手：金蝶云苍穹ERP的开发与数据分析，涵盖表单元数据建模、插件开发与热部署、数据可视化报告。",
   "keywords": [
     "dsh",

package/skills/cosmic-build/AGENTS.md

@@ -10,7 +10,8 @@
 - 禁止在这里复制子技能的命令或流程。只加载一个已选中的子技能入口及其明确要求的引用。
 - 使用确定性 CLI 契约和已验证 API。禁止发明 API、标识、参数结构或目标所有权。
 - 隔离不同环境；应用级平台调用必须绑定当前选中的应用上下文。
-- 自定义页面交给 `kd-frontend-development`，非苍穹应用交给 `standalone-build`，
+- 自定义页面交给 `kd-frontend-development`，可运行的非苍穹浏览器界面交给
+  `site-builder`，非浏览器应用和 general 应用身份初始化交给 `standalone-build`，
   Java 实现交给对应编码技能。
 - 使用能够产生用户要求结果并完成独立验证的最短命令序列。额外诊断或验证专项只在
   用户明确要求，或选中技能因当前风险明确要求时执行。

package/skills/cosmic-build/CHANGELOG.md

@@ -0,0 +1,3 @@
+2026-09-03 支持元数据样式属性批量修改，完善规则写入、产物卡片与验证测试
+
+2026-08-27 优化了一些问题

package/skills/cosmic-build/CLAUDE.md

@@ -10,7 +10,8 @@
 - 禁止在这里复制子技能的命令或流程。只加载一个已选中的子技能入口及其明确要求的引用。
 - 使用确定性 CLI 契约和已验证 API。禁止发明 API、标识、参数结构或目标所有权。
 - 隔离不同环境；应用级平台调用必须绑定当前选中的应用上下文。
-- 自定义页面交给 `kd-frontend-development`，非苍穹应用交给 `standalone-build`，
+- 自定义页面交给 `kd-frontend-development`，可运行的非苍穹浏览器界面交给
+  `site-builder`，非浏览器应用和 general 应用身份初始化交给 `standalone-build`，
   Java 实现交给对应编码技能。
 - 使用能够产生用户要求结果并完成独立验证的最短命令序列。额外诊断或验证专项只在
   用户明确要求，或选中技能因当前风险明确要求时执行。

package/skills/cosmic-build/LOCAL-PATCHES.md

@@ -0,0 +1,246 @@
+# LOCAL-PATCHES —— 本 preset 对金蝶 app-build 的本地差异清单
+
+> 本文件不是给 agent 读的技能内容，是**维护者备忘**：记录本 preset 与金蝶上游 app-build 的
+> 全部差异，供下次上游更新时按图重贴，不必再做一次考古。
+>
+> 本文件不被 `SKILL.md` 引用，不进入技能提示词闭包。
+
+## 0. 上游基线与来源
+
+| 项 | 值 |
+|---|---|
+| 本次对齐的上游版本 | **0.0.299**（`builtin-skills/.builtin-version`），文件日期 2026-09-29 |
+| 上一次拷贝的快照 | 2026-08-24（早于 0.0.277） |
+| 可用参照基线（更早） | `~/.lingeebuild/config/builtin-skills/app-build`（**0.0.277**，2026-08-28） |
+| 上游目录布局 | `builtin-skills/app-build/`（英文 canonical）+ `builtin-skills/app-build/.locales/zh/`（中文覆盖层） |
+| 本 preset 布局 | 单树：`skills/cosmic-build/`（= 上游 zh 覆盖层拍平，无 `.locales/`） |
+
+上游会把旧的 R/D/E 管线、`capabilities/`、`cosmic-{requirements,design,executor,testing,code-review}`、
+`nano-coding-impl` 整批删除——那些**不是**本 preset 的本地内容，跟随上游删除即可。
+
+---
+
+## 1. 同步取源规则（重要，只拷 zh 会出错）
+
+上游 `.locales/zh` 只是**覆盖层**，不是完整树（0.0.299 时 zh 2645 文件 / canonical 3050 文件）。正确规则：
+
+| 文件类型 | 取哪棵树 | 理由 |
+|---|---|---|
+| `.md`（SKILL/README/知识/参考） | ✅ **zh**（中文原生） | 中文内容，canonical 是英文 |
+| `scripts/**.py` | ⚠️ **canonical 为准** | zh 缺 4 个脚本；且 zh 里有一批**滞后副本** |
+| `schemas/*` | ⚠️ **canonical** | `property-contract-fixture.schema.json` 只在 canonical |
+| `contracts/*` | zh 优先；缺则 canonical | `property-input-index.json`、`property-value-encoding.json`、`operation-rule-write-contracts.json` 只在 canonical，且**被 `cmd_properties.py` 运行时读取** |
+
+### 1.1 必须用 canonical 覆盖的 33 个 `.py`
+
+判定方法：剥掉 docstring 与全部字符串常量后比对 AST，仍有差异者为"代码级滞后"。
+其中 **16 个与替换前的 DSH 旧版逐字节相同**（= zh 根本没更新，拷了等于没升级）：
+
+```
+脚本/测试（16 个 zh==旧DSH）:
+  scripts/discovery_snapshot.py          ← 坏档：仍 import 已删的 _shared.property_names
+  scripts/meta_export.py
+  scripts/test/test_appconfig_load.py
+  scripts/test/test_build_meta_order.py
+  scripts/test/test_http_client.py
+  scripts/test/test_kd_token_cache.py
+  scripts/test/test_run.py
+  scripts/test/test_runtime_tool_opt_in.py
+  skills/cosmic-meta-api/modules/pdm/scripts/pdm_auto.py
+  skills/cosmic-meta-api/scripts/_core/markdown.py
+  skills/cosmic-meta-api/scripts/test/test_field_decorator.py
+  skills/cosmic-meta-api/scripts/test/test_formatters_output_isolation.py
+  skills/cosmic-meta-modeling/scripts/post_build_ui.py
+  skills/openapi-gen/scripts/api/constants.py
+  skills/openapi-gen/scripts/metadata/fetcher.py
+  skills/openapi-gen/scripts/metadata/parser.py
+
+三者各不同（14 个，zh ≠ canonical ≠ 旧DSH）:
+  scripts/run.py                          ← 注意：本补丁 #1 的落点
+  scripts/test/test_kd_auth.py
+  scripts/test/test_register_plugins.py
+  skills/cosmic-meta-api/scripts/_core/{config,cmd_properties,cmd_forms,cmd_metaops,cmd_workspace,formatters}.py
+  skills/cosmic-meta-api/scripts/meta_verifier.py
+  skills/cosmic-meta-api/scripts/test/test_form_extension_flow.py
+  skills/cosmic-meta-modeling/scripts/{artifact_validator,dynamic_form_validator}.py
+  skills/openapi-gen/scripts/api/gen_runner.py
+
+DSH 无、新版新增（3 个）:
+  scripts/test/test_bootstrap_cosmic_context.py
+  skills/cosmic-meta-api/scripts/test/test_add_button_closure.py
+  skills/cosmic-meta-api/scripts/test/test_existing_form_ui.py
+```
+
+### 1.2 不要照抄的东西
+
+- `.locales/zh/scripts/discovery_snapshot.py` —— 上游 zh 的坏档，用 canonical 版。
+- `.locales/zh/skills/cosmic-meta-api/scripts/cosmic_api.py` —— 上游自报 drift（612793 vs 613053），取 canonical。
+- `scripts/test/test_bd_bindings.py` —— 上游遗留孤儿（`import bd_bindings` 已随模块删除），zh 独有，不要拿。
+- 两个 `basedata.db`（`cosmic-meta-knowledge/reference-data/`、`cosmic-meta-modeling/knowledge/`）
+  —— 与 canonical 逐字节相同（md5 `a5fe24841647e68880b1456e5e6e8603`），**不要覆盖**。
+
+---
+
+## 2. 本地补丁（17 处，必须重贴）
+
+> 全部相对「导入提交」`ab0a3907`。取补丁的最权威方式：
+> `git -C ~/.dsh/.agent-presets/cosmic diff ab0a3907 <当时的提交> -- skills/cosmic-build/<file>`
+
+| # | 文件 | 位置 | 内容 | commit | 上游是否已有 | 重贴方式 |
+|---|---|---|---|---|---|---|
+| 1 | `scripts/run.py` | `parse_entry()` | `sub_type in ('MulBasedataProp','SubEntryProp')` —— 补 `SubEntryProp`，否则**子单据体字段静默丢失** | `5ed112a2` | ❌ 上游至今未修 | 手工（新版 `run.py` 取 canonical，上下文为英文注释） |
+| 2 | `scripts/_http_client.py` | `_read_response()` + 3 处 `Accept-Encoding: gzip` | 服务端 gzip 响应自动解压 | `cad318d6` | ❌ 上游 0 处 gzip | 自动 patch |
+| 3 | `scripts/appconfig_load.py` | `appconfig_path()` | 回退改为 `<cwd>/app/config/appconfig.json`（上游为 `~/kd/appconfig.json`） | `a5afae4c` | ❌ | 自动 patch |
+| 4 | `scripts/kd_env_loader.py` | `_kd_config_path()` | 工作区 `<cwd>/.dsh/cosmic/.kd/config.json` 优先 + 首次从 `skills/config.json` 模板幂等拷贝（per-workspace 凭证隔离） | `144d32bf` | ❌ | 自动 patch |
+| 5 | `scripts/kd_env_loader.py` | `_build_section()` | 增 `password`；`tenantId` 去掉 `default="ierp"` | `144d32bf` / `0f8378b8` | ❌ | 自动 patch |
+| 6 | `scripts/kd_env_loader.py` | `update_default_kd_env()`、`update_pdm_kd_config()` | `client_secret` / `x-acgw-identity` **明文直写**（绕开 Windows 沙箱加密子进程提权） | `8fdbd0eb` | ❌ | 自动 patch |
+| 7 | `scripts/kd_auth.py` | `build_login_payload()` | `logintype='2' + password`（DeepSeekHarness 环境登录必需；上游是 `usertype='Mobile'`） | `144d32bf` | ❌ | 自动 patch |
+| 8 | `scripts/kd_token_cache.py` | `_get_env_name()` | 读工作区 `.dsh/cosmic/.kd/config.json` | `144d32bf` | ❌ | 手工 |
+| 9 | `scripts/kd_token_cache.py` | `_get_env_name()` | `encoding="utf-8-sig"`（BOM 容忍） | `1456baec` | ✅ 上游已同 | 无需 |
+| 10 | `scripts/kd_token_cache.py` | `put()` | 加密失败时**明文兜底** | `8fdbd0eb` | ❌ | 手工 |
+| 11 | `scripts/entity-download.py` | `_download_one_via_runpy()` | 下载后删除 `{eid}.operate.md` / `.form.md` / `_getFormMetadata_raw.txt`，只留 `entity.md` | `5ed112a2` | 文件不存在 | 随文件整体恢复 |
+| 12 | `scripts/entity-download.py`、`batch-download.sh`、`build_entity_index.py`、`references/entity-download.md` | — | **本地新增**的实体元数据下载工具链 | `5a1281a8` | 文件不存在 | 从 git 恢复 |
+| 13 | `skills/cosmic-meta-api/scripts/_core/config.py` | `_API_PATH` | 新增端点 `getEntityOperate` `getIsv` `getControl` `dataQuery` `dataQueryWithPagination` `getApiByUrl`；`_api_call()` 增 `callApiByUrl` 分支（相对路径拼 base、GET/POST、拆分 base 与 path 避免 token 缓存 key 用错 base 而重新登录） | `3799f741` | ❌ 全树 0 命中 | 手工 |
+| 14 | `config.py` + `skills/cosmic-meta-api/scripts/cosmic_api.py` | `_API_PATH` + argparse/dispatch | 7 个 KSQL 端点与 7 个 CLI 子命令：`ksqlListDbRoutes` `ksqlListDbTypes` `ksqlListTables` `ksqlListColumns` `ksqlTranslate` `exportKSQLByTable` `exportKSQLByObject` | `fa63b366` | ❌ 全树 0 命中 | `cosmic_api.py` 可自动 patch；`config.py` 手工 |
+| 15 | `config.py` | `_HEX_ENCODE_FIELDS` + `_encode_api_params()` + `_api_call()` 钩子 | dataQuery 的 `filters`/`selectFields`/`orderBys` 发送前 **hex 编码**绕过网关 SQL 检测（配套服务端 `DataServiceController.decodeHex`） | `e04fe9c1` | ❌ | 手工 |
+| 16 | `skills/cosmic-meta-api/scripts/field_decorator.py` | `_is_standard()` | 原判定整段注释，**强制 `return True`**（命名强制标准模式、无 ISV 前缀） | `08b32778` | ❌ 上游保留 `isv=='kingdee'` | 自动 patch |
+| 17 | `skills/cosmic-meta-api/modules/pdm/scripts/pdm_client.py` | `resolve_credentials()` 两处 | `tenant_id` 不再默认 `"ierp"` | `0f8378b8` | ❌ | 自动 patch |
+
+### 2.1 风险分级（重贴时按此顺序）
+
+1. 🔴 **`config.py` #13/#14/#15** —— 丢了 = preset 的**数据分析能力全断**
+   （`erp-analysis` 及 4 个 `analysis-*` 技能都 `from _core.config import _api_call` 调 `dataQuery`）
+2. 🔴 **凭据三件套 #4/#5/#6/#7/#8/#10** —— 必须成套改，否则登录失败 / 凭证落到 `~/.kd` / Windows 下写配置失败
+3. 🟠 **#1 `run.py`** —— 子单据体字段丢失（上游未修）
+4. 🟡 #2 gzip、#3 appconfig、#16 命名、#17 tenantId
+5. 🟢 #11/#12 本地工具链（整体保留即可）
+
+---
+
+## 3. 本地独有文件（非补丁，同步时整体保留）
+
+| 路径 | 说明 | commit |
+|---|---|---|
+| `skills/cosmic-vibe-coding/`（8 文件） | build jar 热部署运行手册（R0–R5）+ `dev.py` + `kd-reloadjar-agent.jar`。**工作区 `AGENTS.md` 与 `.dsh/cosmic/scripts/hotdeploy.sh` 写死了它的路径** | `ecf604a6` 等 |
+| `skills/config.json` | 工作区凭证模板（`kd_env_loader` 首次会拷到 `<cwd>/.dsh/cosmic/.kd/config.json`）。**含明文 client_secret，不进 git 分发** | `4362de67` |
+| `skills/tenant.json` | 多项目清单（8 项），`erp-analysis/scripts/erp-config.py` 消费 | `895e8875` |
+| `erpdb/`（28M / 3904 文件） | 本地元数据缓存，上游没有 | — |
+| `scripts/entity-download.py`、`batch-download.sh`、`build_entity_index.py`、`references/entity-download.md` | 实体元数据分层下载工具链 | `5a1281a8` |
+
+> ⚠️ **判定"本地资产"的唯一依据是 git**：`git -C <preset> diff ab0a3907 HEAD -- skills/cosmic-build`
+> 里出现过的才是本地改动/新增。**"只在上游旧版存在、新版已删"的文件不算本地资产**，必须跟随
+> 上游删除——例如曾误判为本地保留的 `capabilities/report_design/SKILL.md` 与
+> `skills/cosmic-meta-modeling/checklists/modeling-checklist.md`，二者均随导入提交引入、
+> 被上游 0.0.299 删除，且**上游守卫测试明确断言其不得存在**（见 §5 第 0 步）。
+
+---
+
+## 4. 下次上游更新的操作流程
+
+```bash
+SRC=<profile>/config/builtin-skills/app-build      # 含 canonical + .locales/zh
+DST=~/.dsh/.agent-presets/cosmic/skills/cosmic-build
+
+# 0) 备份（git 已是完整安全网：全部文件均已跟踪）
+cp -a $DST /tmp/cosmic-build.bak-$(date +%F)
+
+# 1) zh 打底，排除全部本地资产
+rsync -a --delete \
+  --exclude 'erpdb/' --exclude 'skills/cosmic-vibe-coding/' \
+  --exclude 'skills/config.json' --exclude 'skills/tenant.json' \
+  --exclude 'references/entity-download.md' \
+  --exclude 'scripts/entity-download.py' --exclude 'scripts/batch-download.sh' \
+  --exclude 'scripts/build_entity_index.py' \
+  "$SRC/.locales/zh/." "$DST/"
+
+# 2) canonical 补齐 zh 缺失（不覆盖中文版）
+rsync -a --ignore-existing --exclude '.locales/' "$SRC/." "$DST/"
+
+# 3) canonical 覆盖「代码级滞后」文件（见 §1.1，用 AST 比对重新判定）
+
+# 4) 重贴 §2 的 17 处补丁（先 config.py，再凭据三件套）
+
+# 5) 机械适配
+#    a. {APP_BUILD_ROOT} → {ROOT_DIR}（md 与 py 中花括号 token 形态；
+#       注意 py 里还有同名 Python 变量，不要一起改）
+#    b. md 链接标签里的 .locales/zh/ 前缀去掉
+#    c. 确认根 SKILL.md 里 {ROOT_DIR} 与 {python} 的绑定说明仍在
+```
+
+### 4.1 如何重新判定「代码级滞后」
+
+用 AST 剥掉 docstring 和全部字符串常量后比对 zh 与 canonical，仍不同即为代码级差异
+（只差注释/错误文案的不算）。参考实现见本文件 §5 的校验脚本思路。
+
+---
+
+## 5. 验证清单（每次同步后必跑）
+
+```bash
+D=~/.dsh/.agent-presets/cosmic/skills/cosmic-build
+PY=$DSH_HOME/cache/cosmic/venv/bin/python          # 必须是苍穹专用 venv
+
+# 0) 上游架构守卫：以下路径必须不存在（对应上游 scripts/test/test_modeling_flow_mitigations.py
+#    的 test_removed_workflow_surface_does_not_return；保持同步即可自动通过）
+for p in capabilities skills/cosmic-design/SKILL.md skills/cosmic-executor/SKILL.md \
+         scripts/modeling_gate.py \
+         skills/cosmic-meta-modeling/CORE-RULES.md skills/cosmic-meta-modeling/TASK-ROUTING.json \
+         skills/cosmic-meta-modeling/checklists/modeling-checklist.md \
+         skills/cosmic-meta-modeling/prompts/repair-prompt.md \
+         skills/cosmic-meta-modeling/prompts/requirement-system-prompt.md \
+         skills/cosmic-meta-modeling/references/build-core.md \
+         skills/cosmic-meta-modeling/references/build-extensions.md \
+         skills/cosmic-meta-modeling/references/parse-extensions.md \
+         skills/cosmic-meta-modeling/references/zero-confirm-runbook.md ; do
+  [ -e "$D/$p" ] && echo "❌ 上游已删但本地仍在: $p"
+done
+echo "guard: 以上无输出即为通过"
+
+# 1) 17 处补丁逐点存在性
+grep -q "sub_type in ('MulBasedataProp', 'SubEntryProp')" $D/scripts/run.py
+grep -q '_read_response'            $D/scripts/_http_client.py
+grep -q 'os.getcwd()) / "app"'      $D/scripts/appconfig_load.py
+grep -q 'ws_cfg = Path(os.getcwd())' $D/scripts/kd_env_loader.py
+grep -q '明文直写'                   $D/scripts/kd_env_loader.py
+grep -q 'logintype'                 $D/scripts/kd_auth.py
+grep -q 'Path(os.getcwd()) / ".dsh"' $D/scripts/kd_token_cache.py
+grep -q 'token_cipher = token'      $D/scripts/kd_token_cache.py
+grep -q '"dataQuery":'              $D/skills/cosmic-meta-api/scripts/_core/config.py
+grep -q '_HEX_ENCODE_FIELDS'        $D/skills/cosmic-meta-api/scripts/_core/config.py
+grep -q '命名规则强制标准模式'        $D/skills/cosmic-meta-api/scripts/field_decorator.py
+
+# 2) 端点与 hex 编码
+$PY -c "
+import sys; sys.path.insert(0,'$D/skills/cosmic-meta-api/scripts')
+from _core import config as c
+need=['dataQuery','dataQueryWithPagination','getApiByUrl','getEntityOperate','getIsv','getControl',
+      'ksqlListDbRoutes','exportKSQLByTable','exportKSQLByObject']
+print('缺端点:', [k for k in need if k not in c._API_PATH] or 'OK')
+p={'filters':\"fnumber like 'A%'\"}; c._encode_api_params(p); print('hex:', p['filters'][:20])
+"
+
+# 3) 语法编译
+find $D -name __pycache__ -type d -exec rm -rf {} +
+python3 -m compileall -q $D/scripts $D/skills && echo "compileall OK"
+
+# 4) 端到端只读冒烟（在工作区根执行，走工作区凭证）
+cd <工作区> && $PY $D/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout queryForms --keyword "过磅"
+# 期望：退出码 0、stdout 为 JSON、stderr 出现 [auth] OK
+```
+
+2026-09-29 同步后的实测结果：17/17 补丁通过、compileall 退出码 0、
+`queryForms` 冒烟 `[auth] OK` 且命中 16 条表单、`describeCommand` 返回 15.5KB 契约、
+markdown 断链 60 条（与上游 KD zh 完全一致，无新增）。
+
+---
+
+## 6. 已知遗留（不影响运行）
+
+1. **35 个上游 dev 测试**里有 `.locales/zh/...` 硬路径假设，在单树布局下会失败；
+   这些不是运行时依赖（且当前 venv 未装 pytest）。要修就批量去掉该前缀，但保留
+   `scripts/sync_generated_locale_assets.py`、`scripts/check_platform_drift.py`、
+   `scripts/refactor/split_commands.py`（它们讲的**就是**双树布局）。
+2. 上游 `prompt-budgets.json` 的测量口径（`maxClosureKb: 8`，markdown 引用闭包 maxDepth=6）
+   与实测不符——上游大量使用 inline-code 路径而非 md 链接。**不要据此判违规**。
+3. 上游 zh 覆盖层自身有漂移：pytest 默认跳过点目录，故 `.locales/zh/scripts/test/` 下的
+   37 个镜像测试从不执行（上游自承 32 个已漂移）。**不要把 zh 的测试当验收依据。**

package/skills/cosmic-build/README.md

@@ -1,85 +1,73 @@
-# AppBuild
+# app-build
 
-AppBuild 是金蝶云苍穹元数据和后端开发技能。
+面向金蝶云苍穹的业务开发助手。描述业务结果和目标应用，app-build 利用现有平台对象、
+元数据命令，以及必要时的 Java 编码路径，将需求落实到应用中。
 
-## 当前架构
+## 当前产品范围
 
-新工作项采用单一规格、CLI-first、agent-native 工作流：
+| 用户任务 | 可以交付的工作 | 完成边界 |
+|---|---|---|
+| 完善已有单据 | 增加信息、调整布局、补充引用、计算或列表行为，并保留其他配置 | 要求的配置已修改并独立读回，复用已有对象 |
+| 新增业务对象 | 创建头体单据或基础资料，并配置要求的关系、默认值、规则和列表 | 完整交付已明确的配置，澄清缺失的业务选择 |
+| 调整业务规则 | 修改阈值、编辑状态、保存/提交检查，原位调整已有规则或操作校验 | 在指定时机落实效果；要求改旧规则时保留原对象 |
 
-```text
-用户输入
-  → 验证应用/环境/ownership
-  → 草稿 app-spec.<workNo>.md
-  → 用紧凑 CLI 目录观察，按需 describe
-  → 持续修订同一 Spec，直到目标状态一致
-  → 只有观察无法消除业务阻塞时才澄清
-  → 一次隐式或显式批准
-  → AI 即时组合 skill、CLI 和代码
-  → 确定性效果 + 独立读回
-  → execution.<workNo>.jsonl
-  → 使用同一份 spec 验收
-```
-
-用户输入是不完整、甚至可能冲突的期望状态约束集合，不是 capability 调用。模型
-负责解析语义和组合可用原语，确定性 CLI 负责观察与改变真实状态。Spec 是边界与
-验收契约，不是串行推理流水线。
+这是有限范围的开发助手承诺，不代表所有 ERP 应用和平台组合都已达到无人值守生产交付水平。
+现有报表、生命周期和插件能力继续通过各自契约使用，不因这个范围而被移除。
 
-动作目录是开放执行词汇，不是有限意图路由器。所有平台 CLI 都可通过紧凑目录发现，
-只在需要时 describe。目录未命中不等于不支持；两次成功执行也不必使用相同命令
-序列。确定性指应用绑定、批准目标、安全不变量和验证结果一致。
+## 怎样提出需求
 
-## 职责划分
+提供应用或当前对象、希望实现的业务结果，以及关键业务约束。已有字段名称即可，
+不需要先提供平台 ID、CLI 名称或正式需求文档。
 
-| 层 | 职责 |
-|---|---|
-| `SKILL.md` | 入口安全、单一 spec 生命周期、技能选择、完成判断 |
-| 选中的子技能 | 领域判断和动作专属执行 |
-| `scripts/action_catalog.py` | capability 与平台 CLI 的统一、建议性发现 |
-| `scripts/app_spec.py` | Spec 初始化、修订、验证、批准、diff 和 hash 绑定 |
-| `scripts/capability_tool.py` | metadata 的确定性 describe/plan/apply/verify/reconcile |
-| 原子平台 CLI | 目标解析、平台写入、独立读回 |
-| Host harness | 子代理生命周期、并发和上下文管理 |
+例如：
 
-## 持久化工作项契约
-
-```text
-app/{appCode}/
-├── app-spec.{workNo}.md
-├── archive.json
-└── _runtime/
-    ├── context.json
-    ├── requirement-input.{workNo}.md
-    ├── execution.{workNo}.jsonl
-    ├── app-spec-history/{workNo}/
-    └── direct-*.plan.json
-```
+- “费用管理应用中，报销明细超过‘核定标准’时，提交前必须填写‘超标说明’，保留现有提交检查。”
+- “新增服务申请单，引用现有客户资料，包含服务明细、行金额和总金额，可以按申请编号查询。”
+- “把原有锁定规则的阈值从 200 改成 100，保留同一条规则、启用状态和正反向动作。”
 
-- `app-spec` 是唯一活动业务语义 SSOT。
-- `requirement-input` 是不可变原文证据。
-- `execution` 是 append-only、hash-chain 机器账本。
-- Plan 是不可变运行证据；spec revision 改变后必须重新生成。
+标准、计算方式或执行时机不明确时，app-build 应澄清这个业务选择，自己解析技术细节。
+需求指向现有基础资料时应复用，不能为了生成引用字段而擅自新建同名资料。
 
-## 写入安全
+## 怎样理解结果
 
-目录可见性不授权写入。Capability mutation 使用不可变 plan、重放保护、独立读回
-和明确的 `unknown_after_write` 处理。直接平台动作必须传 bootstrap 的 `appRoot`、
-使用 JSON stdout，并为效果绑定已批准 Spec 和独立读回。目标绑定、验证或恢复契约
-不足时，动作仍可发现但不得自动执行。
+- **配置已完成**：要求的变更已保存并独立读回，实际变更的对象提供预览入口。
+- **已满足**：有准确范围的当前证据已匹配要求，避免不必要的写入和重复卡片。
+- **部分完成／待补充信息**：说明已完成的业务范围和具体剩余要求，包括需要 Java 或缺少平台能力的部分。
 
-## 旧流程兼容
+运行效果、业务记录保存和发布只有实际执行后，才能报告已验证。字段或按钮可见，
+并不能证明保存校验、审批流程或生产部署已经完成。
 
-`cosmic-requirements`、`cosmic-design`、`cosmic-executor`、design manifest、
-development plan 和 tasks 文件只用于完成已有的 `routeMode=standard` 工作项。
-新工作项使用 `routeMode=agent`，不得创建或进入旧 R/D/E 管线。
+生产发布、完整审批和权限设计、业务数据迁移、外部系统集成需要各自明确的要求和受支持的
+交付路径，不因“创建一个表单”而自动完成。
 
-## 验证
+## 本地运行文件与 Git
 
-核心检查：
+app-build 会把可恢复输入、编译产物和本地身份状态保留在应用根目录，因为后续会话和编码交接
+仍可能引用这些路径。应用目录会获得一段受管 `.gitignore`：
 
 ```text
-python3 scripts/test/test_app_spec.py
-python3 scripts/ci_quality_gate.py
-python3 scripts/check_prompt_budgets.py
+/_runtime/
+/metadata/_emit/
+/modify/
+/archive.json
+/archive.json.lock
 ```
 
-主要测试位于 `scripts/test/`。
+应用根目录的 `.gitignore` 只需提交一次；`metadata/datamodel/` 和应用源码等真正交付物照常提交。
+运行目录不会自动删除，清理应当由明确操作按会话或保留期限执行。忽略规则不会修改 Git 索引；
+在该策略生效前已经被跟踪的文件，需要仓库负责人明确执行一次取消跟踪。
+
+## 实现边界
+
+根 [`SKILL.md`](SKILL.md) 将业务需求交给已有执行入口；CLI 承担目标身份、平台表示、
+有限写入、保留与读回验证。宿主提供应用/技能上下文和常规展示，不从模型轨迹推断业务完成。
+普通交付不要求统一规划器、工作项 manifest 或执行 ledger。
+
+维护中的运行路径：
+
+- `skills/cosmic-meta-api`：平台 CLI 与机器契约
+- `skills/cosmic-meta-modeling`：新建实体、页面、报表和菜单
+- `skills/cosmic-meta-modifier`：已有表单及元数据修改
+- `skills/cosmic-meta-ui`：布局与呈现元数据
+- `skills/cosmic-coding-impl`：超出元数据能力的 Java 行为
+- `skills/cosmic-meta-knowledge`：按需使用的平台知识