openyida 2026.7.19 → 2026.7.21

package/yida-skills/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: openyida
 description: >
-  宜搭 AI 应用开发总入口技能。通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）+ 宜搭低代码平台，实现一句话生成完整应用。
-  包含应用创建、表单设计、自定义页面开发、页面发布、登录态管理等完整开发流程。
+  宜搭 AI 应用开发总入口技能。通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）+ 宜搭低代码平台，实现一句话搭建或修改完整应用。
+  包含资源上下文解析、应用创建/复用、表单设计/更新、自定义页面开发、页面发布、登录态管理等完整开发流程。
   当用户提到"宜搭"、"yida"、"低代码"、"创建应用"、"创建表单"、"发布页面"、"搭建"、"系统"等关键词时，使用此技能；以下情况不要触发：只是讨论通用前端/后端代码、非宜搭平台产品、或只需要解释概念而不操作宜搭资源。
 ---
 
 # 宜搭 AI 应用开发指南
 
-通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）+ 宜搭低代码平台，实现一句话生成完整应用。所有操作通过 **`openyida`** CLI 统一执行，命令自动读取 `.cache/auth-token-<env>.json`，并在业务请求中携带 `Authorization: Bearer <access_token>`；token 不可用时执行 `openyida login` 重新登录。
+通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）+ 宜搭低代码平台，实现一句话搭建或修改完整应用。所有操作通过 **`openyida`** CLI 统一执行。IF 未设置 `YIDA_AUTH_ENABLED=true`：默认 OAuth token，token 不可用才执行 `openyida login`。IF `YIDA_AUTH_ENABLED=true`：进入宿主注入 token 模式，仅使用 `OPENYIDA_ACCESS_TOKEN` / `OPENYIDA_REFRESH_TOKEN` 等 token env；缺 token 必须 STOP 回宿主，禁止触发 OAuth，禁止读 `.cache/cookies*.json`。
 
 ---
 
@@ -38,33 +38,115 @@ description: >
 |---------|------|
 | 命令跑不了（`command not found`） | openyida 未安装 → `npm install -g openyida` |
 | Node/npm 版本不达标 | 先升级 Node（≥16）再装/升级 openyida |
-| `login.status` 不是 `ok` 且 `login.can_auto_use` 不是 true | 未登录 → `openyida login`（指定入口带 URL 或 flag） |
+| `login.auth_mode=token` 且未登录，且未开启 `YIDA_AUTH_ENABLED` | `openyida login`（指定入口带 URL 或 flag） |
+| `login.auth_mode=token` 且 `auth_source=env` / `failure_reason=env_token_missing` | STOP；宿主必须注入 `OPENYIDA_ACCESS_TOKEN` 或 `OPENYIDA_REFRESH_TOKEN`；禁止触发 OAuth；禁止读 `.cache/cookies*.json` |
 | `workdir_exists` / `active.projectRootExists` 为 false | 无工作目录 → `openyida copy` 初始化 |
 
 **👉 环境异常、登录失败、悟空降级、OAuth token 登录异常等特殊分支 → [references/setup-and-env.md](references/setup-and-env.md)。正常 `agent-capabilities` 通过时不要默认读取该 reference。**
 
 ---
 
-## 第二步：意图路由（先判断「全量搭建」还是「单一任务」）
+## 执行路径：schema-managed 与 direct/standalone
 
-> ⚡ **环境就绪后，先判断用户诉求属于哪一类，再走对应路线**：从零搭一个完整应用，还是对已有资源做单点改动。选错会导致多余步骤或回退；歧义时简短确认一次即可。
+在选择完整应用或单一任务技能前，先判断本次写操作属于哪条执行合同。Agent 只做轻量路由；`schema` 子命令自身强制 validate/plan/apply 与 `planId`，legacy 写命令仅对明确传入的 schema-managed context/state 做最小 fail-closed guard。上下文不足以判断时，先只读确认或询问用户，不由 Agent 猜测 ownership。
+
+| 路径 | 何时选择 | 执行方式 |
+|------|----------|----------|
+| `schema-managed` | 用户提供 Schema-as-Code manifest、要求 `schema validate/plan/apply`，或 CLI/context 明确目标身份来自 Schema-as-Code state | 走 `openyida schema validate <manifest> --json --quiet` → `openyida schema plan <manifest> --state <path> --json --quiet` → 用户审阅本次 `planId` → `openyida schema apply <manifest> --state <path> --plan-id <reviewed-planId> --json --quiet` |
+| `direct/standalone` | 没有 manifest/state 管理关系，或用户明确要求 standalone legacy 命令 | 走下方 Resource-First direct workflow：先解析已有资源，再 create missing only / update / publish |
+
+schema-managed create/update 必须等待用户对当前 `planId` 显式批准；`nextAction`、错误恢复或路由判断都不能授予 `mixed/write`。Phase 1 中 report、automation、page config、delete、pull 不从 Manifest fallback 到 legacy。
+
+`.cache/<项目名>-schema.json` 只是 direct/standalone 的 ID 映射，不等于 Schema-as-Code state。路径不明确时先只读确认或询问用户；不要通过新建同类资源规避不确定性。
+
+---
+
+## 路由前置：resolve_resource_context
+
+> Resource-First Workflow：进入 direct/standalone 路径后，任何完整搭建或单点任务都先解析目标资源上下文，再判断是新建、补齐、修改还是发布。不要把 `create-app` / `create-page` / `create-form` 当作默认动作。
+
+### 资源解析顺序
+
+按以下优先级选择 app/page/form/process，上游来源更明确时覆盖下游来源：
+
+1. 本轮用户明确给出的 `appType`、`formUuid`、应用 URL、页面 URL、流程标识或页面/表单上下文；
+2. agent 或宿主注入的当前任务 resource context；
+3. workspace 中的 `project/config.json`、`.cache/<项目名>-schema.json`、`.cache/openyida/**` 等 standalone cache/config；
+4. 当前会话历史中已创建或已确认的资源；
+5. 无资源且用户明确说“从零创建 / 新建另一个 / 创建新应用或新页面”时，允许创建缺失资源；
+6. 仍有多个同优先级候选、当前轮显式资源互相冲突，或无法判断目标时，才 `ask_human`。
+
+**本轮显式目标覆盖注入上下文**：agent / 宿主注入的 bound app/page/form 只是默认候选，不是锁定目标。若当前会话绑定页面 A，但用户本轮明确给出页面 B 的 URL、`formUuid`、页面名称或其他可识别线索，必须重新解析 B；B 能唯一解析时切换到 B，B 不能唯一解析时 `ask_human`，禁止静默回落到 A。
+
+可选的 agent 注入协议如下；本地 agent 不支持时忽略，不作为运行前置：
+
+```json
+{
+  "kind": "openyida_resource_context",
+  "version": 1,
+  "app": {
+    "appType": "APP_xxx",
+    "source": "explicit_prompt|url|agent_bound|workspace_cache",
+    "precreated": true,
+    "placeholderName": "新应用",
+    "allowCreate": false,
+    "allowRename": true
+  },
+  "page": { "formUuid": "FORM_xxx", "source": "explicit_prompt|url|agent_bound|workspace_cache", "allowCreate": false },
+  "form": { "formUuid": "FORM_xxx", "source": "explicit_prompt|url|workspace_cache", "allowCreate": false }
+}
+```
+
+`precreated` 表示该 app 由 agent / 宿主提前创建并绑定到本轮任务；`placeholderName` 是宿主创建时的占位名；`allowRename` 控制 OpenYida 是否可在语义名稳定后修正应用名称。这些字段都是 direct/standalone 的可选提示：缺失时按普通已有资源处理，不作为运行前置。
+
+**预创建占位 app 改名**：当 `app.source === "agent_bound"`，且满足 `precreated === true` 或当前名称 / `placeholderName` 命中“新应用 / 未命名 / 占位 / APP_xxx”等占位样式，并且 `allowRename !== false`、用户没有明确要求保留原应用名称、目标不是 schema-managed、已从本轮需求确定稳定语义应用名时，`yida-app` 应复用该 `appType` 并调用 `openyida update-app APP_xxx --name "语义应用名"`。该动作只修正 agent 预创建占位应用名称；不要按标题发现/adopt 其他应用，不要 cleanup orphan，不要对非占位已有业务应用自动改名，不要让 `yida-create-app` 参与改名，也不要把 schema-managed 资源交给 legacy `update-app`。
+
+### create-or-update 判定
+
+- 已解析到目标 app 时，默认在该 app 内修改、补齐或发布，不执行 `yida-create-app`；只有用户明确要求“新建另一个应用”并确认目标组织后才创建新 app。
+- 已解析到目标自定义页面 URL / `formUuid` / bound page 时，默认写源码并发布到该页面，不执行 `yida-create-page`；只有缺少目标 display page 且本次意图允许新增页面时才创建。
+- 已解析到目标表单 `formUuid` 时，字段结构诉求默认走 `yida-create-form-page` 的 update/patch/rule/bind-datasource 模式，不创建同名或同类表单。
+- 已解析到目标流程表单 / `processCode` 时，默认走 `yida-process-rule` 配置/更新流程，不从零执行 `yida-create-process`。
+- 完整应用 `fast_build` 也遵守本规则：`resolve app → resolve forms → resolve main page → create missing resources only → update/publish`。
+
+验收心智模型：
+
+| 场景 | 正确动作 |
+|------|----------|
+| `帮我搭建访客系统` + bound app/page | 不 create app/page；直接在已有 app/page 内补表单、写页面并发布 |
+| `在 APP_xxx 里增加客户表和回访页面` | 不 create app；允许按缺口 create form/page |
+| `优化这个页面 URL` | 不 create app/page；直接进入 custom-page + publish existing page |
+| bound 页面 A，但用户说“修复页面 B 的 xx 字段” | 先解析页面/表单 B；B 有 URL/formUuid 时改 B，只有 B 无法唯一识别时询问用户，不能默认改 A |
+| `从零创建一个 CRM 应用` 且无 context | 允许 create app/form/page 并发布 |
+| 多个 app/page 候选 | 按来源优先级选；同级冲突或目标不明才问人 |
+
+> 该 resource context 是 direct/standalone 路径的前置解析；schema-managed 路径仍以 schema CLI 的 validate/plan/apply 结果为准。legacy direct 命令的 guard 只覆盖明确 schema-managed context/state，不替代这里的资源前置解析。
+
+---
+
+## 第二步：意图路由（先判断「完整搭建」还是「单一任务」）
+
+> 环境和 resource context 就绪后，先判断用户诉求属于哪一类，再走对应路线：完整搭建/补齐一个应用，还是对已有资源做单点改动。选错会导致多余步骤或回退；歧义时简短确认一次即可。
 
 | 用户诉求信号 | 判定 | 走哪条路线 |
 |------------|------|-----------|
-| 创建/搭建/做一个 + 应用/系统/管理系统；或明确表达从零开始 | **全量搭建** | 加载子技能 `yida-app`，由它执行完整应用 workflow |
+| 创建/搭建/做一个 + 应用/系统/管理系统；或已有 app/page 需要补成完整系统 | **完整搭建 / 补齐** | 加载子技能 `yida-app`，由它执行 create-or-update workflow |
 | 对已有应用/表单/页面的单点操作（加字段、查改数据、配公式、建报表、改权限、发布、美化…） | **单一 / 增量任务** | 到 [技能路由](#技能路由单一--增量任务) 选定 **1 个**，加载对应子技能执行，不回退流程 |
 
 ---
 
-## 完整开发流程（全量搭建）
+## 完整开发流程（完整搭建 / 补齐）
 
-> 📌 仅当第二步判定为「全量搭建」时进入；单一/增量任务请跳「技能路由」。
+> 📌 仅当第二步判定为「完整搭建 / 补齐」时进入；单一/增量任务请跳「技能路由」。
 > 加载子技能 `yida-app`，由它负责完整应用 workflow、阶段子技能加载、关键 ID 流转、PRD 与 schema cache 约束。
-> 用户说“按默认方案 / 不要追问 / 直接创建 / 尽快搭建”时，`yida-app` 选择 `fast_build`：创建应用、必要表单、主页面、发布并输出链接。
+> 用户说“按默认方案 / 不要追问 / 直接创建 / 尽快搭建”时，`yida-app` 选择 `fast_build`：先解析并复用已有资源，只创建缺失且允许创建的应用/表单/页面，最后发布并输出链接。
+> `yida-app fast_build` 是 direct/standalone 编排，仅在上方执行路径选择为 direct/standalone 时使用。
+
+**默认链路**：`fast_build` 必须只做 `resolve app → resolve forms → resolve main page → create missing resources only → 编写/更新主页面源码 → 发布 → 返回访问链接`。不要因为应用名里有“看板 / 系统 / 管理”就升级到 `deep_design` 或 `full_demo`。
 
-**默认链路**：`fast_build` 必须只做 `创建应用 → 核心表单 → 主页面 → 编写主页面源码 → 发布 → 返回访问链接`。不要因为应用名里有“看板 / 系统 / 管理”就升级到 `deep_design` 或 `full_demo`。
+**fast_build 默认加载边界**：只加载 `yida-app` 和当前阶段必需的子技能。`yida-create-app`、`yida-create-page`、`yida-create-form-page` 只有在目标资源缺失且本次意图允许创建时才加载；已有资源时进入对应 update / publish 分支。页面默认走 Code Canvas；当用户明确要求普通自定义页面 JSX/Jsx 组件链路，或页面强依赖普通自定义页实例桥（`this.$(fieldId)` / `this.utils.yida.*` / `this.dataSourceMap` / 表单提交或字段双向绑定深度耦合）时，选择 `yida-custom-page`。不要默认加载 `yida-page-uiux`、`yida-data-source-connectors`、`yida-data-management`、`yida-nav-group`、`yida-dashboard`，也不要默认深读 `references/`。
 
-**fast_build 默认加载边界**：只加载 `yida-app` 和当前阶段必需的子技能：`yida-create-app`、`yida-create-form-page`、`yida-create-page`、`yida-canvas-custom-page`、`yida-publish-page`。页面默认走 Code Canvas；当用户明确要求普通自定义页面 JSX/Jsx 组件链路，或页面强依赖普通自定义页实例桥（`this.$(fieldId)` / `this.utils.yida.*` / `this.dataSourceMap` / 表单提交或字段双向绑定深度耦合）时，选择 `yida-custom-page`。不要默认加载 `yida-page-uiux`、`yida-data-source-connectors`、`yida-data-management`、`yida-nav-group`、`yida-dashboard`，也不要默认深读 `references/`。
+**Canvas 数据边界**：完整应用/真实交付页如果展示列表、看板或详情记录，必须优先把本轮真实 `appType/formUuid/fieldId` 写入 `page-spec.json` 的 `dataBinding.mode=form`；需要演示记录时先写入真实表单再读取。未接真实表单且未写入 demo records 时，页面展示空态/入口，不用前端 seedRows 冒充业务数据。
 
 **doneWhen**：`yida-app` 发布主页面成功并输出可访问 URL。到这里默认完成；不要发布后继续 TaskCreate、重复读技能或继续规划。
 
@@ -88,8 +170,8 @@ description: >
 | `yida-skills/analytics` | 报表、统计、图表、ECharts、看板、驾驶舱、大屏 | `yida-report`、`yida-chart`、`yida-dashboard` |
 | `yida-skills/integration` | 连接器、外部 API、执行动作、设计器数据源、集成自动化、逻辑流 | `yida-integration`、`yida-connector`、`yida-connector-safe-actions`、`yida-data-source-connectors` |
 | `yida-skills/access` | 平台/应用/表单/页面权限、公开访问、分享 | `yida-corp-manager`、`yida-app-permission`、`yida-form-permission`、`yida-page-config` |
-| `yida-skills/ops` | SLS、日志、traceId、灰度、Sequence、主键冲突、VOC 反馈 | `sls-log-workbench`、`yida-db-seq-fix`、`yida-voc` |
-| `yida-skills/agent` | 大文件写入、导出对话、会议纪要/闪记转 PRD | `large-file-write`、`yida-export-conversation`、`yida-flash-note-to-prd` |
+| `yida-skills/ops` | Sequence、主键冲突、VOC 反馈 | `yida-db-seq-fix`、`yida-voc` |
+| `yida-skills/agent` | 导出对话、会议纪要/闪记转 PRD | `yida-export-conversation`、`yida-flash-note-to-prd` |
 
 ### 高频分歧
 
@@ -126,6 +208,7 @@ description: >
 
 | 意图 | 直接执行 |
 |------|------|
+| 修改当前 app 信息 / 预创建占位 app 改名 | `openyida update-app` |
 | 聚合表 / 虚拟视图 | `openyida aggregate-table` |
 | 流程表单 AI 审批提示 | `openyida ai-form-setting` |
 | 文生文 / 识图通用 AI 能力 | `openyida ai` |
@@ -138,26 +221,28 @@ description: >
 ### 致命规则（FATAL，违反即失败/报错）
 
 1. **技能加载唯一入口**：执行任何子技能前，支持 `use_skill` 的宿主必须调用 `use_skill("<技能名>", "<本阶段目的>")` 加载对应技能；不要用 `Read` / `read_file` / `cat` 读取 SKILL.md 路径，不凭记忆猜参数格式。
-2. **corpId 一致性检查**：创建页面前对比 prd 与 token session 中的 corpId，不一致必须询问用户（重新登录 or 当前组织新建）。
+2. **corpId 一致性检查**：创建或发布页面前对比 prd/resource context 与当前 auth context（默认 token session；`YIDA_AUTH_ENABLED=true` 时为宿主注入 token）的 corpId，不一致必须询问用户（重新登录到目标组织，或确认在当前组织继续操作已解析资源/缺失资源）。
 3. **发布前本地校验**：普通自定义页面 `.oyd.jsx` / `.jsx` 发布前跑 `openyida check-page` + `openyida compile`；Code Canvas `.canvas.jsx` 不跑这两个普通自定义页面检查，改由 `openyida publish` 的 Canvas 编译阶段或 `compileCanvasLocal` 快检校验；JSON 配置写盘后先解析校验，再调用平台命令。
-4. **命令输入文件禁止 shell 写入**：当 OpenYida 命令需要 JSON/YAML/CSV/config/script 文件参数时，先使用当前 agent 运行时提供的结构化文件写入工具（如 create_file / Write / file edit tool）创建文件，再把路径传给命令；禁止用 shell heredoc、`cat`/`echo`/`printf`/`tee` 加输出重定向，或把命令 stdout 重定向成业务文件。
+4. **页面源码修改必须发布闭环**：只要本轮 Write/Edit/Create 了页面源码 `project/pages/src/*.{canvas.jsx,canvas.tsx,oyd.jsx,jsx,tsx}`（含完整搭建、补齐、已有页面 update path、单点优化），final 前必须看到成功的 `openyida publish <source> <appType> <displayPageFormUuid>` 命令结果；本地文件编辑、diff、本地校验或编译只证明源码可发布，不等于远端页面已更新。若没有 publish 成功证据，final 只能说“源码已修改，尚未发布”，禁止说“页面已更新 / 已重新发布 / 已上线”。
+5. **命令输入文件禁止 shell 写入**：当 OpenYida 命令需要 JSON/YAML/CSV/config/script 文件参数时，先使用当前 agent 运行时提供的结构化文件写入工具（如 create_file / Write / file edit tool）创建文件，再把路径传给命令；禁止用 shell heredoc、`cat`/`echo`/`printf`/`tee` 加输出重定向，或把命令 stdout 重定向成业务文件。
 
 ### 重要规则（IMPORTANT，影响质量/性能/可维护性）
 
 1. **按阶段加载必要技能**：按意图选 1 个主技能；完整应用按阶段加载当下唯一需要的子技能，禁止并发批量读取多个 `SKILL.md` 或预读未来阶段技能。
-2. **优先复用缓存**：`appType`/`formUuid`/`fieldId` 优先从 `.cache/<项目名>-schema.json` 读，缺失再 `get-schema`。
-3. **模板优先**：复杂产物先用 `openyida sample` 或现有示例生成骨架，再做最小改动。
-4. **配置承载优先于代码**：字段/公式/联动/报表/审批/集成交给对应技能，自定义页面只做展示与胶水。
-5. **数据性能优先**：统计聚合用 `yida-report` 服务端聚合，不在前端拉全量后自行聚合。
-6. **避免无效重试**：失败先查登录态/组织/参数/字段 ID，无修改不连续重试超 1 次。
-7. **配置分两处存**：业务语义 → `prd/<项目名>.md`；Schema ID → `.cache/<项目名>-schema.json`（prd 不记 ID）。
-8. **临时文件入 project `.cache/`**：OpenYida 业务中间文件写入 `<projectRoot>/.cache/openyida/<项目名或任务名>/`；Schema ID 映射仍写 `<projectRoot>/.cache/<项目名>-schema.json`。从 workspace 根执行命令时使用 `project/.cache/...`，从 project 工作目录内执行时使用 `.cache/...`；不要写仓库根目录或系统临时目录。
-9. **报表美化先问方案**：用户说"优化/美化报表"时先问选原生报表(`yida-report`)还是 ECharts(`yida-chart`)。
-10. **主题技能优先**：涉及应用主题色、品牌色、全局换肤或 `--color-brand1-*` 时先读 `yida-theme`；表单和页面只消费主题，不要在局部 Schema/JSX 中随意写死蓝色/紫色等品牌色。
+2. **Resource-First**：任何 legacy 写操作前先解析本轮显式资源、agent bound context、workspace cache/config、历史上下文；已有目标资源时默认修改/补齐/发布，只有目标缺失且意图允许创建时才加载 create 类技能。
+3. **优先复用 direct 映射**：仅对 direct/standalone 资源，已有 `.cache/<项目名>-schema.json` 中可确认新鲜的 `appType`/`formUuid`/`fieldId` 可复用；该文件不是 Schema-as-Code state，也不是远端真相。字段缺失、重名或结构变化时执行 `get-schema --compact --resolve-fields`，不得猜测。
+4. **模板优先**：复杂产物先用 `openyida sample` 或现有示例生成骨架，再做最小改动。
+5. **配置承载优先于代码**：字段/公式/联动/报表/审批/集成交给对应技能，自定义页面只做展示与胶水。
+6. **数据性能优先**：统计聚合用 `yida-report` 服务端聚合，不在前端拉全量后自行聚合。
+7. **避免无效重试**：失败先查登录态/组织/参数/字段 ID，无修改不连续重试超 1 次。
+8. **配置分两处存**：业务语义 → `prd/<项目名>.md`；Schema ID → `.cache/<项目名>-schema.json`（prd 不记 ID）。
+9. **临时文件入 project `.cache/`**：OpenYida 业务中间文件写入 `<projectRoot>/.cache/openyida/<项目名或任务名>/`；Schema ID 映射仍写 `<projectRoot>/.cache/<项目名>-schema.json`。从 workspace 根执行命令时使用 `project/.cache/...`，从 project 工作目录内执行时使用 `.cache/...`；不要写仓库根目录或系统临时目录。
+10. **报表美化先问方案**：用户说"优化/美化报表"时先问选原生报表(`yida-report`)还是 ECharts(`yida-chart`)。
 11. **按 schema 证据选技能**：先看 `formType`、组件树、`dataSource.online`；`receipt/process/report` 分别落到表单/流程/报表技能。
 12. **官方示例范式优先**：蒸馏官方示例时先理解脱敏 schema 承载方式，不凭截图/标题/视觉判断。
 13. **默认完成即停止**：完整应用默认以发布成功并输出 URL 为 doneWhen；UIUX、数据源深读、示例数据、导航、截图、TaskCreate 和深度设计都是 optionalAfterDone。
-14. **任务复盘沉淀**：任务完成前判断是否有可复用经验需要落盘到 CLI、测试、sample 或 skill。用户多次纠正、平台接口假成功、sample 共性质量问题、线上回读验收方法、一次性脚本可产品化等情况必须沉淀；详见 `references/task-retrospective.md`。
+14. **主题技能优先**：涉及应用主题色、品牌色、全局换肤或 `--color-brand1-*` 时先读 `yida-theme`；表单和页面只消费主题，不要在局部 Schema/JSX 中随意写死蓝色/紫色等品牌色。
+15. **任务复盘沉淀**：任务完成前判断是否有可复用经验需要落盘到 CLI、测试、sample 或 skill。用户多次纠正、平台接口假成功、sample 共性质量问题、线上回读验收方法、一次性脚本可产品化等情况必须沉淀；详见 `references/task-retrospective.md`。
 
 > 📖 每条规则的完整说明、PRD 质量门槛、临时文件路径规范、报表美化话术 → [references/development-rules.md](references/development-rules.md)
 
@@ -168,9 +253,9 @@ description: >
 | 问题 | 处理 |
 |------|------|
 | 发布提示登录失效 | 先 `openyida login`，再 `openyida publish <源文件> <appType> <formUuid> --health-check` |
-| 查已有表单的字段 ID | `openyida get-schema <appType> <formUuid>`，从 Schema 读各字段 `fieldId`（详见 `yida-get-schema`） |
-| 更新已有表单字段 | 用 `create-form` 的 update 模式：`openyida create-form update <appType> <formUuid> '[{"action":"add","field":{"type":"TextField","label":"新字段"}}]'`（详见 `yida-create-form-page`） |
-| 发布提示 corpId 不匹配 | 问用户：当前组织新建应用发布，或 `openyida logout` 后重新登录到正确组织 |
+| 查已有表单的字段 ID | `openyida get-schema <appType> <formUuid> --compact --resolve-fields "字段名"`，仅使用唯一命中的 `fieldId`（详见 `yida-get-schema`） |
+| 更新已有表单字段 | direct/standalone 表单用 `create-form` 的 update 模式：`openyida create-form update <appType> <formUuid> '[{"action":"add","field":{"type":"TextField","label":"新字段"}}]'`（详见 `yida-create-form-page`）；schema-managed 表单走 schema validate → plan → apply |
+| 发布提示 corpId 不匹配 | 问用户：确认在当前组织继续操作已解析资源，或 `openyida logout` 后重新登录到正确组织 |
 
 ---
 

package/yida-skills/references/schema-as-code-phase1.md

@@ -0,0 +1,99 @@
+# Schema-as-Code Phase 1 Manifest
+
+这是 OpenYida Phase 1 唯一的 Manifest 编写与执行指南。Phase 1 管理 `app`、`form`、`process` 和 `native/default` 展示页；State 是资源 identity bindings 的唯一持久化权威，但 State 不是远端真相。
+
+## Canonical Manifest
+
+页面源码必须是 workspace 内的相对路径。下面的流程节点、字段和资源都使用稳定 semantic key；不要把真实 `appType`、`formUuid`、`fieldId` 或 `processCode` 写进 Manifest。
+
+```json
+{
+  "kind": "openyida_app_manifest",
+  "schemaVersion": 1,
+  "app": {
+    "key": "visitorSystem",
+    "name": "访客管理系统"
+  },
+  "forms": {
+    "visitorRegistration": {
+      "title": "访客登记",
+      "mode": "process",
+      "fields": {
+        "visitorName": {
+          "type": "TextField",
+          "label": "访客姓名",
+          "required": true
+        },
+        "visitReason": {
+          "type": "TextareaField",
+          "label": "来访原因"
+        }
+      }
+    }
+  },
+  "processes": {
+    "visitorApproval": {
+      "form": "visitorRegistration",
+      "nodes": [
+        {
+          "key": "frontdeskReview",
+          "type": "approval",
+          "name": "前台初审",
+          "approver": "originator"
+        }
+      ]
+    }
+  },
+  "pages": {
+    "visitorHome": {
+      "title": "访客工作台",
+      "source": "pages/visitor-home.oyd.jsx"
+    }
+  }
+}
+```
+
+上例不是单文件即跑：先在 workspace 内创建或替换 companion source `pages/visitor-home.oyd.jsx`，再执行 `validate`。例如文件内容可以是：
+
+```jsx
+export default function Page() {
+  return <div>访客工作台</div>;
+}
+```
+
+更新页面时也先替换同一个 workspace-relative source 文件，再重新 `plan`；不要把 inline source、绝对路径或真实页面 ID 写进 Manifest。
+
+## Review Then Apply
+
+```bash
+openyida schema validate app.yida.json --json --quiet
+openyida schema plan app.yida.json --state .cache/openyida/state.v1.json --json --quiet
+openyida schema apply app.yida.json --state .cache/openyida/state.v1.json --plan-id '<reviewed-planId>' --json --quiet
+```
+
+1. `validate` 只做本地校验。
+2. `plan` 使用 `remote_read` 权限读取线上真实状态。人工检查 changes 和 `planId`。
+3. 对任何正常 create/update，首次 `apply` 都必须由用户审阅本次 `planId` 后显式批准，才以 `mixed/write` 权限执行。baseline plan、State、缓存、成功的 validate/plan 或错误 action 都不能激活写权限。
+4. form/page 保存使用本次 apply JIT exact read 得到的 `gmtModified`；app/process 没有同类条件写，继续使用 identity/version/JIT/reconciliation 门禁。
+
+## Actions
+
+- 正常结果不触发错误恢复型 `ask_human`；但任何 create/update 的 plan 完成后都必须独立暂停，等待用户对当前 `planId` 的显式批准，才可执行首次 `apply`。
+- `stale_replanned` 只展示 replacement plan，等待用户重新审阅并显式 apply；绝不自动 apply 或重试 save。
+- `nextAction=ask_human` 时使用宿主 ask_human；没有工具时原样展示安全的 `blockText` 和 `choices`。
+- `nextAction`、`ask_human` 和 `choices` 只用于错误恢复或业务取舍，不构成首次或后续 `apply` 的写授权。
+- reconciliation、uncertain create/write、managed conflict/missing 时停止。禁止自动 retry、按标题 discover/adopt、猜 ID、cleanup 或重建。
+
+## Phase 1 Boundary
+
+| Resource or operation | Phase 1 |
+| --- | --- |
+| app/form/process/native-default display page create/update/noop | Supported |
+| report、integration automation | `SCHEMA_RESOURCE_TYPE_UNSUPPORTED` |
+| page config、delete、pull、adopt | Deferred; not Manifest v1 properties |
+| Canvas、dashboard、raw Schema、inline page source | Deferred/unsupported |
+
+Standalone、明确 unmanaged 且用户明确要求 legacy 命令的资源仍可使用原 CLI。SAC Manifest 或 State 已拥有资源身份时，不得 fallback 到 legacy 直写。
+
+- SAC-owned Manifest 中的 report、automation、page config、delete 和 pull 在 Phase 1 停止或延期，不 fallback 到 legacy。
+- 明确 standalone/unmanaged 的 report、integration automation 和 page config 仍可路由现有 `yida-report`、`yida-integration`、`yida-page-config`；delete/pull 当前没有 Phase 1 live Manifest 或 standalone routing contract。

package/yida-skills/references/setup-and-env.md

@@ -1,91 +1,91 @@
-# 环境准备与登录检测
+# setup-and-env
 
-> **本文档的功能**：执行任何宜搭操作前，按序检测并准备运行环境与登录态。**下方 6 步全部通过前，禁止创建应用/页面/表单或发布等真实资源操作。**
-
-## 检查流程（按序执行，全绿才可操作）
-
-先跑两条只读命令拿快照，再对照下表逐步判断：
+## Run First
 
 ```bash
-openyida env --json                  # 环境快照：装没装 / AI 工具 / project / 登录态
-openyida login --check-only --json   # 只读 token 登录态，不触发登录、不建资源
+openyida agent-capabilities --summary-json
 ```
 
-| # | 检查项 | 判断依据 | 未通过时处理 |
-|---|--------|---------|-------------|
-| 1 | openyida 是否安装 | `env` 能跑并返回 `{"ok": true}` = 已装 | 报 `command not found` / 非零退出 → `npm install -g openyida`（先确认 Node ≥16） |
-| 2 | openyida 版本 | `env` 能跑但报错 / 行为异常 = 版本过旧 | `npm install -g openyida@latest` 后重试；仍异常 → `openyida doctor` 逐项体检 |
-| 3 | Node 版本 | 需 **Node.js ≥ 16**；`env` 只报告 `system.node`，不做校验 | 安装或运行报版本错 → 先升级 Node，再装/升级 openyida |
-| 4 | 登录态 | `login.loggedIn` 为 true 或 `login.status=ok` = 已登录 | 为 false → `openyida login`；指定入口须带 URL 或 flag（见「多环境登录」），勿退化成裸 `openyida login` |
-| 5 | project 工作目录 | `active.projectRootExists` 为 true | 为 false → `openyida copy`（非悟空工具须先 `cd` 到工程根目录，见「初始化 project」） |
-| 6 | 特殊环境 | 悟空 / Codex | 悟空命令连续失败 → 转人工诊断；Codex → 使用默认 OAuth token 登录（见对应章节） |
-
-## 命令速查
+Fallback:
 
 ```bash
-npm install -g openyida            # 安装
-npm install -g openyida@latest     # 更新到最新（命令报错多因版本旧，更新后重试即可）
+openyida env --json
+openyida login --check-only --json
 ```
 
-| 命令 | 定位 | 何时用 |
-|------|------|--------|
-| `env --json` | 机器可读快照：装没装 / 工具 / project / 登录 | 每次操作前（主命令）。恒返回 `ok:true`，`system.node` 仅报告不校验 |
-| `login --check-only --json` | 只读 token 登录态，不触发登录/不建资源 | 登录后二次验证 token session 写入 |
-| `auth status` / `auth refresh` | 查看或刷新 token 登录态 | access token 过期、业务命令鉴权失败时 |
-| `doctor` | 人读深度体检：校验 Node ≥16（ERROR）、npm ≥7（WARNING）、config.json、token 登录态、网络；支持 `--fix` / `--report`，无 `--json` | `env` 报错或行为异常时排查 |
+## Auth Mode
 
-## env --json 关键字段
+- IF `login.auth_mode=token`: OAuth token mode.
+- IF `YIDA_AUTH_ENABLED=true`: host-injected token mode; the host must provide token env such as `OPENYIDA_ACCESS_TOKEN` or `OPENYIDA_REFRESH_TOKEN`.
+- NEVER infer auth from `.cache/cookies*.json`.
 
-| 字段 | 含义 | 用途 |
-|------|------|------|
-| `ok` | 恒为 `true`（命令能跑即为真） | 不能用来判断是否安装 |
-| `system.node` | 运行时 Node 版本 | 仅报告，是否达标看 `doctor` |
-| `active.tool` | 当前活跃 AI 工具（悟空/OpenCode/Aone 等） | 决定 project 目录位置 |
-| `active.projectRootExists` | `project/` 是否存在 | 为 `false` → `openyida copy` |
-| `active.isWukong` | 是否悟空环境 | 决定 project 目录位置 |
-| `login.loggedIn` / `login.canAutoUse` | 是否已登录 / 可自动使用 | 为 `false` → `openyida login` |
-| `login.corpId` / `login.baseUrl` | 组织 ID / 域名 | corpId 一致性检查 |
+## Decision Table
 
-不带 `--json` 直接跑 `openyida env` 时，输出报告分三块：
+| Snapshot | Next action |
+|---|---|
+| command not found | install/update `openyida`; do not create resources |
+| `workdir_exists=false` or `active.projectRootExists=false` | run `openyida copy`; do not create resources before workspace exists |
+| `auth_mode=token`, `status=ok` or `can_auto_use=true` | continue |
+| `auth_mode=token`, `failure_reason=env_token_missing` | STOP; host must inject `OPENYIDA_ACCESS_TOKEN` or `OPENYIDA_REFRESH_TOKEN`; do not run OAuth |
+| `auth_mode=token`, not logged in, `YIDA_AUTH_ENABLED` is not true | run `openyida login`; verify with `openyida login --check-only --json` |
+| `auth_mode=token`, access token expired | run `openyida auth refresh`; if still failed and `YIDA_AUTH_ENABLED` is not true, run `openyida login` |
 
-| 报告项 | 显示内容 |
-|--------|---------|
-| AI 工具检测 | 当前活跃的 AI 工具（悟空 / OpenCode / Aone Copilot 等） |
-| 当前生效环境 | 项目根目录路径 |
-| 登录态检测 | 是否已登录、域名、组织 ID；显示"未登录"就先 `openyida login` |
+## Token Mode Commands
 
-## 多环境登录
+Use OAuth login only when `YIDA_AUTH_ENABLED` is not true.
 
-登录指定入口时命令必须带该 URL、`--endpoint` 或环境 flag，否则会落到默认公有云 `www.aliwork.com` / `auth-token-public.json`。例如阿里内网 `https://yida-group.alibaba-inc.com/`：
+```bash
+openyida login
+openyida login --check-only --json
+openyida auth status
+openyida auth refresh
+openyida auth logout
+```
+
+If user gives target entry URL or environment:
 
 ```bash
 openyida login https://yida-group.alibaba-inc.com/
-openyida login --alibaba                              # 等价简写
+openyida login --alibaba
+openyida login --intl
 ```
 
-## Codex / Agent token 登录
-
-当前登录默认是 OAuth token 模式：`openyida login` 会打开钉钉 OAuth 授权页，用户完成登录后回调到本机 loopback 地址，CLI 换取并保存 `access_token` / `refresh_token`。Codex 或其他 agent 环境中不要再走旧 Cookie / QR handoff，也不要手动导出 Cookie。登录完成后**必须**再执行 `openyida login --check-only --json` 或 `openyida auth status` 验证 token session 写入，验证通过前不得创建真实资源。
+Overseas / international / global / Japan / Global YiDA => add `--intl` or equivalent.
 
-## 悟空（Wukong）降级规则
+## Host-Injected Token Mode Commands
 
-悟空环境本地命令入口连续失败时，不要继续重试，也不要判定为登录失败。转人工协同诊断：请用户在可用终端执行以下低风险命令并贴回输出：
+Use only when `YIDA_AUTH_ENABLED=true`.
 
 ```bash
-openyida -v
+openyida agent-capabilities --summary-json
 openyida env --json
 openyida login --check-only --json
+openyida auth status
+openyida auth refresh
+```
+
+Allowed result:
+
+```json
+{
+  "auth_mode": "token",
+  "auth_source": "env",
+  "status": "ok",
+  "can_auto_use": true
+}
 ```
 
-确认 `loggedIn` / `can_auto_use`、`auth_mode=token`、`corp_id`、`base_url` 等关键项前，禁止创建任何真实宜搭资源。
+If the host did not inject token env, failure result includes `failure_reason=env_token_missing`; stop the task and go back to the host. Do not launch OAuth from this mode.
 
-## 初始化 project 工作目录
+## NEVER
 
-`active.projectRootExists` 为 false（切换 AI 工具、新工程首次使用）时执行 `openyida copy`。目录位置随工具而定：
+- Never run `openyida login` in host-injected token mode.
+- Never read `.cache/cookies*.json` as yida-agent auth.
+- Never ask the user to export browser Cookie.
+- Never print Cookie, CSRF, `access_token`, or `refresh_token`.
 
-| AI 工具 | project 目录位置 | 执行要求 |
-|---------|-----------------|---------|
-| **悟空（Wukong）** | `~/.real/workspace/project`（专属 workspace，与工程目录无关） | 直接执行 |
-| **其他工具**（Aone Copilot / Cursor / Claude Code / OpenCode 等） | `<当前工程目录>/project` | 须先 `cd` 到工程根目录再执行 |
+## Wukong / Codex
 
-> ⚠️ 对于非悟空工具，必须先 `cd` 到工程根目录再执行 `openyida copy`，否则 `project/` 会铺错位置。
+- Same auth mode rules as above.
+- Do not special-case Wukong or Codex into OAuth login when `YIDA_AUTH_ENABLED=true`.
+- Do not create app/page/form/publish until auth snapshot is usable.

package/yida-skills/references/task-retrospective.md

@@ -84,22 +84,22 @@ OpenYida 任务完成后，除了交付当前结果，还要判断是否有可
 
 这轮 `Chart - *` sample 暴露出的核心问题是：自定义 ECharts 页面引用了旧应用里的 `REPORT_xxx`、旧 `prdId/topicId` 和旧 `cid`，在当前 Samples 应用中会返回 `no permission for the report`。以后遇到 chart sample 权限或空数据问题时，按下面链路处理。
 
-1. **先在当前应用创建或同步原生报表**  
+1. **先在当前应用创建或同步原生报表**
    不要把另一个应用的 `REPORT_xxx` 复制到当前页面。当前应用如果没有可用数据源表单，先创建专用数据源表单并写入可展示的示例数据；再用 `openyida create-report` 创建原生报表。
 
-2. **所有绑定参数来自新报表 schema**  
+2. **所有绑定参数来自新报表 schema**
    创建报表后必须 `openyida get-schema <appType> <REPORT_xxx> --json`，从组件树提取 `cid`、`componentName/className`、`dataSetKey`、`filterKey`、`cname`。不要沿用旧 `YoushuTable_mmx...` 或旧 `YoushuSimpleIndicatorCard_mmx...`。
 
-3. **`prdId/topicId` 运行时动态获取**  
+3. **`prdId/topicId` 运行时动态获取**
    ECharts 页面不能硬编码 `prdId`。用 `getFormNavigationListByOrder` 按 `REPORT_FORM_UUID` 找 `topicId`，再调用 `getDataAsync.json`。
 
-4. **filterKey 是组件级，不是字段级**  
+4. **filterKey 是组件级，不是字段级**
    同一个“状态筛选”联动到不同组件时也会生成不同 `filterKey`。记录时用 `statusTableStatus`、`budgetTableStatus` 这类组件级命名，不能只写 `status`。
 
-5. **绑定关系要落盘并加测试**  
+5. **绑定关系要落盘并加测试**
    写入 `.cache/openyida/<任务名>/report-binding.json`，同时在 `tests/sample.test.js` 或相关测试中断言 sample 不再包含旧 `REPORT`、旧 `prdId`、旧 appType 或旧 cid 前缀。
 
-6. **发布后全量验收**  
+6. **发布后全量验收**
    对所有 chart sample 执行 `check-page`、`compile`、`publish --health-check`、`git diff --check`。如果页面使用了 ECharts 地图，要同时检查地图底图/GeoJSON 兜底，不允许把“地图组件暂不可用”作为正常态。
 
 ### 沉淀优先级