weaver-work-cli 0.1.6 → 0.1.7

package/skills/weaver-e10-shared/references/weaver-e10-installation.md

@@ -15,6 +15,45 @@ weaver-work-cli skills list
 
 `weaver-work-cli skills list` 只证明包内 Skill 文件可读，不证明业务 API 可用；E10 登录态和 live API 仍需按业务命令实际验证。
 
+## 命令找不到（退出码 127）：先区分「未安装」与「已安装但不在 PATH」
+
+`weaver-work-cli --version` 报 `command not found` 或退出码 127 时，**不要直接判定为未安装并重装**。CLI 可能已安装在非默认 npm 前缀下，只是当前 shell 的 PATH 未包含全局 bin 目录。按顺序处理：
+
+1. 定位全局 bin 目录（macOS/Linux bash/zsh）：
+
+```bash
+npm prefix -g
+npm bin -g 2>/dev/null || echo "$(npm prefix -g)/bin"
+ls "$(npm prefix -g)/bin" | grep -i weaver
+```
+
+Windows PowerShell：
+
+```powershell
+npm prefix -g
+Get-ChildItem "$(npm prefix -g)" -Filter "weaver-work-cli*" -Recurse -Depth 1 -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName
+```
+
+2. 若能在全局 bin 目录中找到 `weaver-work-cli`，先把它前置到 PATH 再验证，**不要安装**：
+
+macOS/Linux（bash/zsh）：
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+weaver-work-cli --version
+```
+
+Windows PowerShell：
+
+```powershell
+$env:Path = "$(npm prefix -g);$env:Path"
+weaver-work-cli --version
+```
+
+PATH 前置后仍不可用，或全局 bin 目录里根本没有 `weaver-work-cli`，才判定为「未安装」，进入下一节的来源选择流程。
+
+3. 沙箱/容器环境里若 PATH 前置仍失败，按 [`non-interactive-environment.md`](non-interactive-environment.md) 收尾：记录退出码与耗时并反馈，不自动执行全局安装。
+
 ## Agent 自动安装运行时
 
 当 `weaver-work-cli --version` 失败或用户要求代装时，Agent 先让用户选择来源；未同意前不改全局 npm 环境。

package/skills/weaver-e10-shijingran/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: weaver-e10-shijingran
+description: 泛微E10事井然项目管理助手，覆盖项目和任务的创建、查询、修改、删除操作，以及项目/任务类型、紧急程度、状态等字典查询。当用户需要创建/管理项目或任务时触发使用。
+display_name: 泛微E10事井然项目管理
+display_name_en: Weaver E10 Shijingran Project Management
+description_zh: 泛微E10事井然项目管理助手，封装项目和任务的创建、查询、修改、删除操作，并提供项目/任务类型、紧急程度、状态等字典查询能力。适用于在对话中通过 Agent 创建、查询、修改、删除项目或任务等场景。
+description_en: Weaver E10 Shijingran project management assistant. Covers CRUD operations for projects and tasks, and provides dictionary queries for project/task types, priorities, and statuses. Used when an Agent needs to create, query, modify, or delete projects or tasks in conversation.
+version: 1.0.7
+author: 泛微网络科技股份有限公司
+agent_created: true
+requires:
+  bins: ["weaver-work-cli"]
+cliHelp: "weaver-work-cli project --help"
+---
+
+# 泛微E10事井然项目管理
+
+## 适用场景（何时使用本技能）
+
+用户要创建、查询、修改或删除事井然项目与任务，或查项目/任务的类型、状态、紧急程度等字典时使用本技能。
+
+用户处理的是流程审批、组织人员或发票时，转对应业务技能，不在本技能范围。
+
+## CRITICAL：共享规则
+
+先读取 [`../weaver-e10-shared/SKILL.md`](../weaver-e10-shared/SKILL.md)。若该文件不存在，先执行 `weaver-work-cli skills install shared --target-dir <当前Agent的Skills目录>`；若 CLI 未安装，先执行 `npm install -g weaver-work-cli`。安装或读取失败时必须停止执行。
+
+## 路由
+
+命中以下意图时按表路由到对应 operation 和 reference；不要为了普通查询执行 `project schema`、`project.version.check`、`project.form.fields` 或读取非必要 reference。
+
+| 意图 | operation | reference | 备注 |
+| --- | --- | --- | --- |
+| 查询任务/项目列表 | `project.task.list` / `project.project.list` | [operations.md](references/operations.md) | `@me` 直接传 `filters.manager` / `filters.participant(s)` |
+| 查询任务/项目详情 | `project.task.detail` / `project.project.detail` | [operations.md](references/operations.md) | |
+| 查询任务/项目类型、状态、优先级 | `project.dictionary.*` | [operations.md](references/operations.md) | |
+| 应用/对象 ID、字段定义、字段选项 | `project.app.ids`、`project.object.id`、`project.form.fields`、`project.form.options` | [operations.md](references/operations.md) | 仅自定义字段或异常排查 |
+| 关联表单按名称查记录 | `project.form.data.page` | [field-resolution.md](references/field-resolution.md) | |
+| 按姓名解析员工/部门/分部 | `project.employee/department/subcompany.resolve` | [field-resolution.md](references/field-resolution.md) | 多个匹配必须让用户选择 |
+| 版本异常诊断 | `project.version.check` | [operations.md](references/operations.md) | 仅接口异常或用户主动询问 |
+| 创建/修改/删除任务或项目 | `project.task/*`、`project.project/*` 的 prepare/apply | [write-operations.md](references/write-operations.md) | 严格 prepare → apply |
+
+## 高优先级语义
+
+- 事井然、项目管理、项目、任务、待办任务、任务列表、项目列表、任务详情、项目详情。
+- 我负责的任务、我参与的任务、我负责的项目、我参与的项目、所属项目、父任务、父项目。
+- 创建/新建项目或任务、修改/编辑项目或任务、删除项目或任务。
+- 任务类型、任务状态、任务紧急程度/优先级、项目类型、项目状态、项目优先级。
+- 负责人、参与人、测试负责人、客户经理、验收负责人、所属部门、所属分部、关联表单字段。
+
+## 处理链
+
+1. 判断用户目标对象和最小必要条件，按路由读取最小必要 reference；已知出厂字段直接使用 `operations.md` 的字段 quick reference。
+2. 名称条件先解析为 ID；0 个匹配要告知，多个匹配必须让用户选择，不得猜。
+3. 查询默认第 1 页 10 条；返回条数等于 pageSize 时提示可能还有更多，等待用户要求再翻页。
+4. 列表和详情中不要单独输出 `detail_url` 列；将 `task_name` / `proj_name` 渲染为 Markdown 链接（方括号内为记录名称，紧跟的圆括号内为 `detail_url` 的取值）。链接不可用时名称保持纯文本并如实说明，不得编造 URL。
+5. 写操作先 `prepare`，向用户摘要目标、差异、风险、默认值和不可逆性；用户明确确认后才 `apply`。
+6. `partial/write_uncertain`、登录失效、回查失败或网络中断时停止写流程，不自动重试。
+
+## 执行原则
+
+- 业务调用统一使用 `weaver-work-cli --json project run <operation>`，优先 `--input-json`；复杂多行 JSON 用 UTF-8 文件和 `--input <path>`。
+- 列表展示只保留用户所需字段；普通列表也用 `fields` 对齐展示列，不要拉回全部原始字段；关联类字段取 `name`，不展示内部 ID。
+- 同一会话已确认 CLI 可用、登录态有效且字段语义无变化时，不要重复执行版本、认证或 schema 诊断；“我负责/我参与”直接使用 `@me`；同一会话已解析的名称→ID、字典 ID、对象 ID 直接复用。
+- 大结果需要检查时先用 operation 内置过滤/裁剪参数，必要时再落盘为 UTF-8 JSON 并用 Node 解析；不要依赖 `grep`、`head`、`wc` 等 shell 工具。仅做摘要、统计、筛选或名称转 ID 时，优先 `withDetailUrl:false` 和 `fields` 裁剪输出；`fields` 不含 `detail_url` 时可少一次链接解析请求。
+- 不要把接口原始路径、Cookie、ETEAMSID或 Token 作为用户可执行步骤。
+- 接口异常后才调用版本诊断；版本低于 `20.6.11` 时提示升级，不重试原接口。
+
+## 写操作失败决策树
+
+1. `apply` 缺少 `confirm: true` 或 continuation：停止，重新执行 `prepare` 并取得用户确认。
+2. `target_changed`：目标已变化，重新回查并重新 `prepare`。
+3. `partial/write_uncertain`：停止，不重试写入；先执行只读详情/列表回查。
+4. 登录失效：按共享规则处理登录，不得使用旧 continuation 直接重试。
+5. 回查失败：向用户说明结果不确定，等待用户决策。
+
+## 不在范围
+
+- 禁止绕过 `weaver-work-cli` 直接调用 E10 原始接口。
+- 不提供附件上传；`attachment` 只接受已上传文件 ID，且处理文件前必须取得用户敏感数据确认。
+- 不自动替用户选择同名人员、组织、项目、任务或字典选项。
+- 不自动翻页、自动扩大 pageSize 或自动聚合全量数据。
+- 不在正常路径预调用版本诊断。

package/skills/weaver-e10-shijingran/references/field-resolution.md

@@ -0,0 +1,105 @@
+# 事井然字段值解析
+
+## 何时使用
+
+仅在以下情况读取本文：
+
+- 用户以名称描述人员、部门、分部、项目、任务、Ebuilder 关联或选择类字段，需要名称转 ID。
+- 字段是自定义字段、字段名不在 `operations.md` quick reference 中，或字段语义不确定。
+- 需要读取关联字段配置、字典选项或写入字段约束。
+
+已知出厂字段直接使用 `operations.md` 的 quick reference，不要先拉全量表单 schema。解析结果仅在当前会话或当前任务内复用；不要写入持久缓存。
+
+## 通用规则
+
+- ID 一律按字符串传递，避免大整数精度丢失。
+- 人员、组织、Ebuilder 关联的纯数字值长度通常大于等于 10 位；已确认是 ID 时直接使用，不要重新解析。
+- 多个 ID 用英文逗号拼接且无空格，例如 `"id1,id2"`；不要传 JSON 数组。
+- 名称转 ID 结果、字典 ID、`groupId`、当前表对象 ID、`refObjId` 和标题字段 `dataKey` 在同一会话内复用；同一名称不要重复解析。
+- 不要用字段显示文本、`text` 或中文名称代替字段名 `name`。
+
+## 人员与组织
+
+- `project.employee.resolve`：输入 `name`、`match: exact|fuzzy`、`status: normal|all`；默认精确匹配在职员工。
+- `project.department.resolve`：输入 `name`、`match`。
+- `project.subcompany.resolve`：输入 `name`、`match`。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json project run project.employee.resolve --input-json '{"name":"张三","match":"exact"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json project run project.employee.resolve --input-json '{"name":"张三","match":"exact"}'
+```
+
+0 个匹配时告知用户；1 个匹配取 `id`；多个匹配列出名称和组织信息让用户选择。多选字段先把每个名称分别解析，再用英文逗号拼接 ID。
+
+用户明确说“我负责”“我参与”时，不需要按姓名解析自己，也不需要执行 `auth status`：直接传 `@me`，CLI 会自动解析为当前登录人。查询过滤用于 `manager`、`participant`、`participants`，写入用于 `manager`。
+
+## 项目与任务名称转 ID
+
+`project` 字段引用项目 ID，`parent_node` 在任务表引用任务 ID、在项目表引用父项目 ID。
+
+| 字段 | 所属表 | 解析目标 | 查询 operation | 名称过滤 |
+| --- | --- | --- | --- | --- |
+| `project` | task | 项目 ID | `project.project.list` | `name`（映射到 `proj_name`） |
+| `parent_node` | task | 任务 ID | `project.task.list` | `name`（映射到 `task_name`） |
+| `parent_node` | project | 项目 ID | `project.project.list` | `name`（映射到 `proj_name`） |
+
+解析步骤：
+
+1. 使用用户提供的名称作为顶层 `name` 模糊查询，`pageNo=1`、`pageSize=10`。
+2. 从 `data.datas[].mainTable` 匹配名称；关联对象输出取 `name`，记录 ID 取 `id`。
+3. 0 个匹配时告知用户；1 个匹配取 `id`；多个匹配列出名称、计划时间和负责人让用户选择。
+4. 将记录 ID 作为字段值填入写入或过滤条件。
+
+示例（解析项目名称“需求评审”）： 
+
+```powershell
+weaver-work-cli --json project run project.project.list --input-json '{"name":"需求评审","pageNo":1,"pageSize":10}'
+```
+
+```bash
+weaver-work-cli --json project run project.project.list --input-json '{"name":"需求评审","pageNo":1,"pageSize":10}'
+```
+
+不要为了按名称解析项目或任务而调用 `project.form.fields`。
+
+## Ebuilder 关联字段
+
+1. `project.form.fields` 获取当前表字段定义，找到目标字段的 `config.refObjId` 和 `config.dataTitle`。
+2. 再次调用 `project.form.fields` 时把 `sourceId` 设为 `config.refObjId`，找到 `id=config.dataTitle` 的字段并取其 `config.dataKey` 作为 `fieldKey`。
+3. `project.form.data.page` 输入 `refObjId=config.refObjId`、`fieldKey`、`value=用户名称`。
+4. 取响应 `datas[0].mainTable.id.fieldValue` 作为业务字段 ID；多条匹配让用户选择。
+
+`project.form.fields` 返回较大时，先保存为 UTF-8 JSON，再用 Node 解析 envelope 的 `data.data[].fields[]`；不要依赖 `grep`、`head`、`wc`。解析示例见 `operations.md` 的“大结果落盘与 Node 解析”。
+
+## Select 与字典字段
+
+`task_type`、`task_status`、`priority`、`proj_type`、`proj_status` 等字典类字段优先使用 `project.dictionary.*`：
+
+| 字段 | 字典 operation |
+| --- | --- |
+| `task_type` | `project.dictionary.task-type` |
+| `task_status` | `project.dictionary.task-status` |
+| `priority`（任务） | `project.dictionary.task-priority` |
+| `proj_type` | `project.dictionary.project-type` |
+| `proj_status` | `project.dictionary.project-status` |
+| `priority`（项目） | `project.dictionary.project-priority` |
+
+1. 用默认或较大 `pageSize` 查询字典。
+2. 按用户输入名称匹配字典记录的名称字段，取记录 `id`。
+3. 优先选择启用项；多个相近选项无法区分时让用户选择。
+4. 解析出的业务状态 ID 传给 `task_status` / `proj_status`，不要再传 `sys_status`。
+
+非字典 Select 字段（如约束类型、排程模式、验收进展）已有出厂枚举；先使用源资料/CLI reference 中的枚举映射。只有枚举无法确认时才用 `project.form.fields` 找字段元数据 `id`，再用 `project.form.options` 查询。
+
+## 注意
+
+- 解析结果只在当前任务内复用；同名或歧义必须重新让用户确认。
+- 不要把全量 schema 或原始认证响应粘贴给用户。
+- 解析失败时不要猜 ID；把候选或缺口告诉用户。

package/skills/weaver-e10-shijingran/references/operations.md

@@ -0,0 +1,154 @@
+# 事井然查询与元数据 operation
+
+## 何时使用
+
+用于项目/任务列表、详情、字典、应用/表单元数据和应用版本诊断。
+
+明确查询意图直接按本文对应小节执行。已知出厂字段先查下方 quick reference；不要为了确认这些稳定字段名调用 `project.form.fields`。只有在自定义字段、关联字段、字典选项或写入语义不确定时，才读取 `field-resolution.md` 并调用元数据 operation。
+
+## 出厂字段 quick reference
+
+`project.task.list` / `project.project.list` 的业务记录位于 `data.datas[].mainTable`。以下字段为出厂稳定字段，可直接使用。"适用"列标"通用"表示任务和项目共用同一字段名。
+
+| 字段名 | 语义 | 适用 | 查询输入 | 输出形态 |
+| --- | --- | --- | --- | --- |
+| `task_name` | 任务名称 | 任务 | 顶层 `name`，模糊匹配 | 字符串 |
+| `proj_name` | 项目名称 | 项目 | 顶层 `name`，模糊匹配 | 字符串 |
+| `task_desc` | 任务描述 | 任务 | 顶层 `description`，模糊匹配 | 字符串 |
+| `proj_desc` | 项目描述 | 项目 | 顶层 `description`，模糊匹配 | 字符串 |
+| `project` | 所属项目 | 任务 | `filters.project`，项目 ID | `[{name,id}]` |
+| `parent_node` | 父任务/父项目 | 通用 | `filters.parent_node`，对应 ID | 字符串或关联对象 |
+| `manager` | 负责人 | 通用 | `filters.manager`，人员 ID | `[{name,id}]` |
+| `participant` | 参与人 | 任务 | `filters.participant`，人员 ID | `[{name,id}]` |
+| `participants` | 参与人 | 项目 | `filters.participants`，人员 ID | `[{name,id}]` |
+| `tester` | 测试负责人 | 任务 | `filters.tester`，人员 ID | `[{name,id}]` |
+| `customer_manager` | 客户经理 | 项目 | `filters.customer_manager`，人员 ID | `[{name,id}]` |
+| `acceptance_manager` | 验收负责人 | 项目 | `filters.acceptance_manager`，人员 ID | `[{name,id}]` |
+| `task_type` | 任务类型 | 任务 | `filters.task_type`，字典 ID | `[{name,id}]` |
+| `proj_type` | 项目类型 | 项目 | `filters.proj_type`，字典 ID | `[{name,id}]` |
+| `task_status` | 业务任务状态 | 任务 | `filters.task_status`，字典 ID | `[{name,id}]` |
+| `proj_status` | 业务项目状态 | 项目 | `filters.proj_status`，字典 ID | `[{name,id}]` |
+| `sys_status` | 系统状态 | 通用 | `filters.sys_status`，`todo`/`doing`/`pause`/`terminated`/`finished` | 系统值 |
+| `priority` | 紧急程度 | 通用 | `filters.priority`，字典 ID | `[{name,id}]` |
+| `progress` | 进度 | 通用 | `filters.progress`，精确匹配 | 字符串或数字 |
+| `plan_start_time` | 计划开始时间 | 通用 | `filters.plan_start_time`，精确匹配 | 字符串 |
+| `plan_finish_time` | 计划完成时间 | 通用 | `filters.plan_finish_time`，精确匹配 | 字符串 |
+| `create_time` | 创建时间 | 通用 | 通常不作为过滤条件 | 字符串 |
+
+- 人员/关联字段查询必须传 ID 字符串；展示取 `name`，不展示内部 ID。
+- `sys_status` 传英文值；`task_status`/`proj_status` 传字典 ID；用户给出业务状态时只传业务状态字段。
+- 自定义字段仍需实时调用 `project.form.fields` 确认，不要从 quick reference 猜测。
+
+## 当前用户“我负责 / 我参与”模板
+
+用户明确说“我负责”“我名下”“我参与”时使用；不要先执行 `auth status`，也不要调用 `project.employee.resolve` 解析当前用户。直接把 `@me` 传给人员过滤字段，CLI 会替换成当前登录用户 ID。
+
+- “我负责的任务/项目”用 `filters.manager="@me"`。
+- “我参与的任务”用 `filters.participant="@me"`；“我参与的项目”用 `filters.participants="@me"`。
+- 用户只说“我的任务/我的项目”时，默认按 `manager` 查询并在结果前说明口径；明确要参与人时再改用上面对应字段。
+
+查询我负责的任务：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json project run project.task.list --input-json '{"filters":{"manager":"@me"},"pageNo":1,"pageSize":10,"withDetailUrl":false,"fields":["task_name","task_type","task_status","manager","plan_finish_time","progress"]}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json project run project.task.list --input-json '{"filters":{"manager":"@me"},"pageNo":1,"pageSize":10,"withDetailUrl":false,"fields":["task_name","task_type","task_status","manager","plan_finish_time","progress"]}'
+```
+
+## 任务与项目查询
+
+- `project.task.list`：`filters` 是源接口 `mainTable` 过滤对象；`name`/`description` 走 URL Query 模糊匹配；默认 `pageNo=1`、`pageSize=10`。
+- `project.task.detail`：仅传 `id`，可用 `fields` 裁剪输出。
+- `project.project.list`：语义同任务列表，项目名称/描述字段由 CLI 映射为 `proj_name`/`proj_desc`。
+- `project.project.detail`：仅传 `id`，可用 `fields` 裁剪输出。
+
+默认状态和分页：
+
+- 未指定状态时，CLI 自动增加 `sys_status="todo,doing"`，即只查未开始和进行中；向用户说明这个口径。
+- 用户指定业务状态时，先把状态名称解析为字典 ID，再传 `task_status` / `proj_status`；此时不要传 `sys_status`。
+- 用户要求全部状态时传 `{"allStatuses":true}`，CLI 不传系统状态和业务状态；不要把五个 `sys_status` 值拼成一个字符串。
+- 返回条数等于 `pageSize` 时可能还有下一页；先提示，不自动翻页或扩大 `pageSize`。
+- 普通列表、详情回查、大结果或上下文敏感场景都传 `fields`，例如任务列表 `["task_name","task_type","plan_start_time","plan_finish_time","manager","task_status","progress","create_time","detail_url"]`；CLI 会保留 `id` 和记录名称字段，裁掉其他原始字段。只有 `fields` 包含 `detail_url` 时才解析详情链接。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json project run project.task.list --input-json '{"pageNo":1,"pageSize":10,"fields":["task_name","task_type","plan_start_time","plan_finish_time","manager","task_status","progress","create_time","detail_url"]}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json project run project.task.list --input-json '{"pageNo":1,"pageSize":10,"fields":["task_name","task_type","plan_start_time","plan_finish_time","manager","task_status","progress","create_time","detail_url"]}'
+```
+
+## 详情链接
+
+- `project.task.list`、`project.project.list`、`project.task.detail`、`project.project.detail` 默认为有记录 ID 的业务数据补充 `detail_url`；传 `fields` 且不包含 `detail_url` 时，CLI 不生成链接，也不调用对象 ID 接口。
+- 任务列表用 `data.datas[].mainTable[].detail_url` 把 `task_name` 渲染为 `[名称](detail_url)`；项目列表用同一位置渲染 `proj_name`。
+- 任务详情用 `data.datas[0].mainTable.detail_url` 把 `task_name` 渲染为 `[名称](detail_url)`；项目详情用同一位置渲染 `proj_name`。
+- 若返回 `detail_url_warning`，说明主查询已成功但链接暂不可用；如实提示，不重试主查询，不编造 URL。
+- 需要最高执行效率时（只做摘要、计数、筛选或名称转 ID），传 `withDetailUrl:false`，或在 `fields` 中不包含 `detail_url`；仅当用户会点开详情或明确要链接时保留默认的详情链接。
+
+## 字典查询
+
+- `project.dictionary.task-type`
+- `project.dictionary.task-priority`
+- `project.dictionary.task-status`
+- `project.dictionary.project-type`
+- `project.dictionary.project-priority`
+- `project.dictionary.project-status`
+
+输入为 `filters`、`pageNo`、`pageSize`；默认每页 100 条。创建/编辑时应优先选择启用项。
+
+## 元数据与版本
+
+- `project.app.ids`：无输入，返回当前环境应用 ID。
+- `project.object.id`：输入 `table: task|project`。
+- `project.form.fields`：输入 `table`，可选 `groupId`、`sourceId`、`detailFieldsGroup`、`enableMerge`；可用 `fieldKeyword` 按字段显示名/字段名过滤，或用 `fieldNames` 精确过滤。仅用于自定义/未知字段、关联字段配置或异常排查，不用于确认 quick reference 中的稳定出厂字段。
+- `project.form.options`：输入 `table`、`fieldName`，可选 `groupId`、`sourceId`、`optionLevel`。
+- `project.form.data.page`：见字段解析 reference。
+- `project.version.check`：可选 `appId`；正常路径不要调用，仅用于接口异常诊断或用户主动询问版本。
+
+`project.form.fields` 可能返回很大的 JSON。业务数据在 envelope 的 `data.data[].fields[]`，字段对象包含 `name`、`text`、`compType`、`config` 等信息。优先传 `fieldKeyword`（如 `自定义`）或 `fieldNames` 缩小返回范围；不要把原始 JSON 全量粘贴给用户。
+
+## 大结果落盘与 Node 解析
+
+`project.form.fields` 优先用 `fieldKeyword` / `fieldNames` 服务端输出过滤；只有仍需复杂二次筛选时落盘。普通任务列表可直接读取工具输出并摘要。不要依赖 `grep`、`head`、`wc` 等 shell 工具。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json project run project.form.fields --input-json '{"table":"task","fieldKeyword":"自定义"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json project run project.form.fields --input-json '{"table":"task","fieldKeyword":"自定义"}'
+```
+
+临时文件只保存业务 JSON，不保存认证信息。解析完成后按宿主规则清理，不在回复中输出完整字段清单。
+
+## 输出处理
+
+- CLI 输入优先用 `fields` 对齐默认展示，不要拉回全部原始字段；读取成功后只向用户摘要业务字段和记录数。
+- 任务列表必须且仅默认展示 `task_name`、`task_type`、`plan_start_time`、`plan_finish_time`、`manager`、`task_status`、`progress`、`create_time`；`task_name` 渲染为 `[名称](detail_url)`，不单独输出 `detail_url` 列。
+- 任务详情必须且仅默认展示 `task_name`、`task_type`、`project`、`manager`、`task_status`、`progress`、`plan_start_time`、`plan_finish_time`、`task_desc`、`create_time`；`task_name` 渲染为 `[名称](detail_url)`，不单独输出 `detail_url` 列。
+- 项目列表必须且仅默认展示 `proj_name`、`proj_type`、`plan_start_time`、`plan_finish_time`、`manager`、`proj_status`、`progress`、`create_time`；`proj_name` 渲染为 `[名称](detail_url)`，不单独输出 `detail_url` 列。
+- 项目详情必须且仅默认展示 `proj_name`、`proj_type`、`priority`、`manager`、`proj_status`、`progress`、`plan_start_time`、`plan_finish_time`、`proj_desc`、`create_time`；`proj_name` 渲染为 `[名称](detail_url)`，不单独输出 `detail_url` 列。
+- 用户明确指定展示字段时，以用户指定为准，但仍不要罗列全部原始字段。
+- 关联字段返回 `[{name,id}]` 时展示 `name`，不展示内部 ID。
+- 明确说明默认状态口径；返回条数等于 `pageSize` 时提示可能有下一页。
+
+## 失败处理
+
+- `endpoint_not_found`、结构不符或语义为接口不存在时，可调用一次 `project.version.check`。
+- 版本低于 `20.6.11`：提示升级，不重试原接口。
+- 权限不足、数据校验错误、空结果不是版本问题，按原始错误处理。