weaver-work-cli 0.1.8 → 0.1.20

package/docs/blog.md

@@ -0,0 +1,123 @@
+# blog — 泛微E10工作日报
+
+`blog` 模块把 E10「工作日报」的查询与写入链路收敛成一组业务 operation，供人和 Agent 统一调用。源资料为生产环境已验证的 `weaver-e10-blog` Agent Skill（v1.3.0，含接口 reference 与实测脚本）。CLI 命令后缀 `blog`，Skill 后缀 `blog`，两者同名；源资料指纹见 `skills/weaver-e10-blog/references/source-manifest.json`。
+
+## 模块来源
+
+- `SKILL.md` 与 `references/blog-*.md`：群体日报查询、单人日报查询、HRM 姓名解析、评论查询、默认共享、导出、发布、编辑、评论、点赞、提醒的接口出入参与实测结论。
+- `references/blog-disabled-capabilities.md`：按 userId 列表批量查个人、unRead、EB 日报应用接口族、删除日报等未暴露能力的判定依据。
+- `scripts/*.mjs`（query-day / query-weaver-e10-blog / publish-blog / edit-blog / comment-blog / like-blog / remind-blog / export-blog）：参数形态与调用顺序样例。
+
+## CLI 结构
+
+```text
+weaver-work-cli blog --help
+weaver-work-cli blog schema
+weaver-work-cli --json blog run <operation> --input-json '<json>'
+weaver-work-cli --json blog run <operation> --input <path>
+```
+
+便捷子命令（均为薄包装，最终调用同一 operation）：
+
+- `blog query` → `blog.query`
+- `blog query-user` → `blog.query_user`
+- `blog resolve-users` → `blog.resolve_users`
+- `blog comments` → `blog.comments`
+- `blog default-permission` → `blog.default_permission`
+- `blog export` → `blog.export`
+- `blog publish|edit|comment|like|remind prepare|apply` → 对应写入链
+
+源码结构：
+
+```text
+src/shortcuts/blog/
+  index.ts            Commander 命令注册、schema/run、便捷子命令、JSON 输入解析
+  manifest.ts         operation 合约清单、输入示例、未暴露能力与理由
+  operations.ts       run 入口：选择 handler、校验输入对象与禁用字段
+  errors.ts           结构化错误（validation/authentication/network/api/confirmation/partial）
+  host.ts             E10 请求适配 + 业务码位置漂移归一化 + 导出流校验
+  continuation.ts     prepare/apply 写入链的确认凭据签发与校验
+  operations/
+    registry.ts       manifest 与 handler 一一对应校验
+    types.ts          operation 类型、统一 JSON Schema 片段
+    shared.ts         输入校验、日期/时区、指纹、HRM 人员解析、导出落点
+    query.ts          blog.query
+    query-user.ts     blog.query_user、blog.resolve_users
+    comments.ts       blog.comments
+    export.ts         blog.export
+    publish.ts        blog.default_permission、发布 prepare/apply
+    edit.ts           编辑 prepare/apply
+    comment.ts        评论 prepare/apply
+    like.ts           点赞/取消点赞 prepare/apply
+    remind.ts         提醒 prepare/apply
+```
+
+## operation 表
+
+| operation | 风险 | 说明 |
+| --- | --- | --- |
+| `blog.query` | read | 群体日报查询（`user_type`：directSubordinate / indirectSubordinate / allSubordinate / myFollow），客户端按日期窗口裁剪；未提交按人天列在 `not_submitted`，整窗未交见 `not_submitted_people` |
+| `blog.query_user` | read | 单人日报查询（detailsByDate 逐日扫描，区间上限 62 天；按人查询的唯一可靠路径；不传 `user_id`/`name` 时查当前登录人）；每天带 `submit_status`，并汇总 正常/补交/未提交 天数 |
+| `blog.resolve_users` | read | HRM 姓名精确解析为 userId（取 `id` 字段，不是 `userid`） |
+| `blog.comments` | read | 查某条日报评论列表（commentPage） |
+| `blog.default_permission` | read | 查某日期默认共享对象，供发布时回填 `permissionList` |
+| `blog.export` | local-file-write | 导出日报 xlsx（拒绝覆盖已存在文件） |
+| `blog.publish.prepare` / `.apply` | read-before-write / high-risk-write | 发布日报；prepare 查当日重复 + 回填默认共享；apply 写前再查重 + 写后回查 |
+| `blog.edit.prepare` / `.apply` | read-before-write / high-risk-write | 编辑日报；prepare 取原内容做差异；apply 指纹校验 + 回查内容一致性 |
+| `blog.comment.prepare` / `.apply` | read-before-write / high-risk-write | 评论日报；目标不存在即报错；apply 从评论列表回查该评论 |
+| `blog.like.prepare` / `.apply` | read-before-write / high-risk-write | 点赞 / 取消点赞；无只读回查接口，以业务码为准 |
+| `blog.remind.prepare` / `.apply` | read-before-write / high-risk-write | 提醒提交；默认文案「请填写 YYYY年 M月 D日 的日报！」；逐人发送，部分失败返回 `PARTIAL` |
+
+withheld（未暴露）：按 userIds 批量查个人（服务端忽略该过滤）、unRead（恒返回空）、EB 日报应用接口族（租户未启用）、删除日报、撤回已发送提醒。理由记录在 `weaver-work-cli blog schema` 的 `withheldOperations`。
+
+## 关键设计
+
+- **补交口径统一**：`createTime`（提交时间）与 `blogTime`（日报日期）同日为 `正常`，跨日为 `补交`，无日报为 `未提交`；不使用 blogs 接口的 `later` 字段（实测不可靠）。
+- **窗口裁剪在客户端**：服务端对 blogs 接口不按 `filter.startDate/endDate` 硬过滤，返回全量倒序；模块按窗口过滤后才统计。
+- **未提交按人天**：`not_submitted[]` 为「人 × 日」粒度（同一人部分日期未交也能暴露），`not_submitted_people[]` 为整窗完全没交的人（用于催交）。
+- **写入链**：`prepare` 只读回查 + 预览 + 签发 continuation；`apply` 强制 `confirm=true` 与有效 continuation，并校验登录上下文（baseUrl/profile/userId）与目标指纹。写请求发出后网络中断返回 `partial/write_uncertain`，禁止自动重试，只能只读回查。
+- **发布防重**：`prepare` 与 `apply` 都会查当日是否已有日报，已存在分别返回 `publish_already_exists` 与 `target_changed`，杜绝重复提交。
+- **导出落盘**：先校验父目录存在与目标文件不存在，再以 `wx` 独占写入，避免 check-then-write 竞态覆盖用户文件；响应缺少 `PK` 魔数即判定非 xlsx。
+
+## 已知限制
+
+- 服务端**忽略 `pageNo`**（实测第 1/2/3 页返回同一批数据），`pageSize` 生效且上限 300；返回行数 ≈ 人数 × 天数，因此默认 `page_size=300` 最大化覆盖。若 `_note` 出现，说明单页已顶满、窗口更早部分未覆盖，需缩小日期范围或人员范围（不要靠调大 `page_no`）。
+- 按 `userId` 列表批量查个人不可用：`filter.userIds/empIds/userId/creator` 被服务端静默忽略（恒定返回当前登录人且 HTTP 200），查个人统一走 `blog.query_user`。
+- 日期区间按天计数、上限 62 天（`blog.query` 与 `blog.query_user` 口径一致），超限返回 `range_too_large`。
+- 点赞无只读回查接口，`verified` 恒为 `false`，生效以业务码为准。
+- EB 日报应用接口族（ebuilder / secondev）未实现：依赖租户是否启用 EB 日报应用，当前租户未启用。
+
+## 安全边界
+
+- 只调用 `/api/` 前缀路径，拒绝跨域、路径逃逸与协议外地址。
+- 认证、Cookie、ETEAMSID、User-Agent 由 `src/internal/e10` 统一托管；业务输入出现 `cookie`/`eteamsid`/`token`/`authorization` 等字段直接报 `field_forbidden`。
+- 不读取、不打印认证目录与认证文件。
+- 导出为本地文件写入，目标已存在时拒绝覆盖（`output_exists`）。
+
+## 测试
+
+单元测试（manifest 合约、各 operation、host 错误映射）：
+
+Windows PowerShell：
+
+```powershell
+npm test -- "test/business/blog-*.test.ts"
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+npm test -- "test/business/blog-*.test.ts"
+```
+
+全量回归（含 Skill 布局校验）：
+
+```bash
+npm test
+```
+
+Skill 质检（安装前必须通过）：
+
+```bash
+weaver-work-cli skills validate skills/weaver-e10-blog --json --no-html
+```

package/docs/caizhilian.md

@@ -0,0 +1,304 @@
+# 采知连（文档中心）CLI
+
+来源 Skill：`weaver-e10-caizhilian`（version 1.1.17）。本模块把源 Skill 的 Python 插件与 HTTP 模板 1:1 转换为 `weaver-work-cli caizhilian` 命令，供 AI Agent 通过结构化 JSON 调用。
+
+源码位于 `src/shortcuts/caizhilian`。命令注册、`operation manifest` 和业务执行逻辑分离：`manifest.ts` 汇总对外契约（含 `withheldOperations`），`operations/registry.ts` 由 `operations/specs.ts` 的 60 条操作规格展开成 87 条对外 operation（写操作展开为 `.prepare` / `.apply`），具体执行逻辑在 `src/shortcuts/caizhilian/operations/handlers` 中按业务分组维护（document、folder、collab、search、fileops、system），公共能力在 `operations/api.ts`、`operations/files.ts`、`operations/form.ts`、`operations/shared.ts`。
+
+面向 Agent 的说明位于 `skills/weaver-e10-caizhilian`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-e10-caizhilian/references/`。
+
+## 公共前置
+
+先通过 E10 鉴权模块登录：
+
+```text
+weaver-work-cli auth login --base-url "https://weapp.xxx.cn" --agent_type "<当前智能体名称>"
+weaver-work-cli auth status --no-check
+```
+
+每个采知连业务请求由 CLI 托管：
+
+1. 读取当前 `weaver-work-cli auth` Profile 的 E10 会话。
+2. 请求统一走 `/api/` 路径（`/api/doc/**`、`/api/file/**`、`/api/hrm/**`、`/api/crm/**`），由 CLI 携带 E10 Cookie/ETEAMSID 与 `User-Agent: AgentType=<agentType>,IsAgent=true`。
+3. 响应按 WeaResult（`code`/`status`/`data`）判定业务成功；`code != 200` 抛 `api/business_error`。
+4. 普通接口超时 12 秒，上传与下载超时 120 秒，单文件下载上限 100MB（源 `assets/config.json`）。
+
+Agent 不得在业务 JSON 中传 Cookie、ETEAMSID、Token 或内部控制字段；环境、配置与登录态由框架统一管理，业务模块不提供环境切换（见「未暴露能力」）。
+
+## Agent 入口
+
+优先使用 `caizhilian run <operation>`；高频动作有薄包装 `caizhilian search` / `caizhilian get` / `caizhilian health`。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli caizhilian schema
+weaver-work-cli caizhilian operations
+weaver-work-cli --json caizhilian health
+weaver-work-cli --json caizhilian search --keywords "季度报告" --folder-id 200 --page-size 10
+weaver-work-cli --json caizhilian get --doc-id 1234567890
+weaver-work-cli --json caizhilian run caizhilian.folder.query-by-name --input-json '{"folder_name":"财务","kb_type":"company"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli caizhilian schema
+weaver-work-cli caizhilian operations
+weaver-work-cli --json caizhilian health
+weaver-work-cli --json caizhilian search --keywords "季度报告" --folder-id 200 --page-size 10
+weaver-work-cli --json caizhilian get --doc-id 1234567890
+weaver-work-cli --json caizhilian run caizhilian.folder.query-by-name --input-json '{"folder_name":"财务","kb_type":"company"}'
+```
+
+成功和失败都使用 JSON envelope。成功写 stdout；失败写 stderr，并设置非 0 退出码。
+
+当前输出层是完整 JSON 直接写 stdout，不提供 `--jq`、`--format table/ndjson` 或通用 `--page-all`。Agent 使用时应默认小页读取和摘要渲染：文档列表先 `page_size=10`，按 `page_no` 继续；`has_next` 的判定是「本页条数 >= page_size」（服务端 `total` 不可信）；回复只展示关键字段和数量，超长响应（正文 HTML、批量结果）落本地文件后给路径。
+
+## Operation 目录
+
+87 条对外 operation，按资源分组。风险等级：只读 = `read`；写前回查 = `read-before-write`（prepare）；高风险写 = `high-risk-write`（apply）；上传写 = `read-with-upload`（apply，会上传本地文件）；本地落盘 = `local-file-write`（写本地磁盘，不改服务端）；外部制品 = `external-artifact`（apply，产出外部链接）。
+
+### document（18 条对外 operation）
+
+文档：检索、详情、创建与编辑
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.document.search` | 只读 | — | `search_documents` | 按关键词/文件夹/创建人/创建时间检索文档（源 search_documents） |
+| `caizhilian.document.get` | 只读 | — | `fetch_doc_base_info_by_docid` | 按 doc_id 获取文档详情（源模板 FetchDocBaseInfoByDocid） |
+| `caizhilian.document.create-html.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `create_html_document` | 在指定文件夹创建 HTML 文档（源 create_html_document） |
+| `caizhilian.document.create-markdown.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `create_markdown_document` | 在指定文件夹创建 Markdown 文档（源 create_markdown_document） |
+| `caizhilian.document.create-office.prepare/apply` | prepare=写前回查，apply=上传写 | prepare → apply | `create_office_document` | 上传 Office 文件并创建文档（源 create_office_document） |
+| `caizhilian.document.create-by-upload.prepare/apply` | prepare=写前回查，apply=上传写 | prepare → apply | `create_document_by_upload` | 批量上传文件直接建文档（源 create_document_by_upload） |
+| `caizhilian.document.update-field.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `update_doc_field` | 修改文档基础字段（源 update_doc_field） |
+| `caizhilian.document.update-author.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `update_doc_author` | 变更文档作者（源 update_doc_author） |
+| `caizhilian.document.update-html.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `update_doc_html_content` | 保存 HTML 正文并生成新版本（源 update_doc_html_content） |
+| `caizhilian.document.replace-content.prepare/apply` | prepare=写前回查，apply=上传写 | prepare → apply | `replace_document_content` | 用本地文件替换文档正文（源 replace_document_content，走 reUpload） |
+
+### folder（24 条对外 operation）
+
+文件夹：创建、虚拟文件夹、默认共享与权限
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.folder.create.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `create_folder` | 创建文件夹（源 create_folder） |
+| `caizhilian.folder.search-virtual` | 只读 | — | `search_virtual_folders` | 检索虚拟文件夹（源 search_virtual_folders） |
+| `caizhilian.folder.query-by-name` | 只读 | — | `query_folders_by_name` | 按名称查询文件夹并展平为路径列表（源模板 FlattenSearchResultFolderTree） |
+| `caizhilian.folder.get-settings` | 只读 | — | `fetch_folder_default_settings` | 查询文件夹默认设置（虚拟目录/默认参与人/默认共享） |
+| `caizhilian.folder.list-default-shares` | 只读 | — | `fetch_folder_default_shares` | 查询文件夹文档默认共享人列表（源入参名为 folderId） |
+| `caizhilian.folder.default-share.form` | 只读 | — | `fetch_folder_set_default_share_form` | 查询“默认共享人”表单配置（对象类型 + 级联参数） |
+| `caizhilian.folder.default-share.list` | 只读 | — | `fetch_folder_set_default_share_list` | 查询“默认共享人”设置列表 |
+| `caizhilian.folder.default-share.add.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `add_folder_set_default_share` | 添加文件夹默认共享人 |
+| `caizhilian.folder.default-share.delete.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `delete_folder_set_default_share` | 删除文件夹默认共享人 |
+| `caizhilian.folder.permission.form` | 只读 | — | `fetch_folder_permission_form` | 查询文件夹文档权限设置的表单配置 |
+| `caizhilian.folder.permission.list` | 只读 | — | `list_folder_permission` | 查询文件夹文档权限设置列表 |
+| `caizhilian.folder.permission.add.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `add_folder_permission` | 添加文件夹文档权限设置 |
+| `caizhilian.folder.permission.delete.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `delete_folder_permission` | 删除文件夹文档权限设置 |
+| `caizhilian.folder.permission.get-auth` | 只读 | — | `fetch_folder_permission_auth` | 查询文件夹权限类型当前值（true/user/false） |
+| `caizhilian.folder.permission.set-auth.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `update_folder_permission_auth` | 设置文件夹权限类型（true/user/false） |
+| `caizhilian.folder.permission.detail` | 只读 | — | `fetch_folder_permission_detail` | 查询文件夹单个设置项详情（含标题与人员明细） |
+| `caizhilian.folder.permission.query` | 只读 | — | `query_folder_permissions` | 批量查询文件夹权限白名单字段（源模板 FilterFolderPermissionFields） |
+| `caizhilian.folder.query-by-permission` | 只读 | — | `query_folders_by_permission` | 按权限类型 + 权限对象反查文件夹 |
+
+### org（8 条对外 operation）
+
+组织人员浏览器
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.org.search-user` | 只读 | — | `search_user` | 人员浏览器检索（源 search_user → /api/hrm/common/browser/data/resource） |
+| `caizhilian.org.search-department` | 只读 | — | `search_department` | 部门浏览器检索（源 search_department） |
+| `caizhilian.org.search-subcompany` | 只读 | — | `search_subcompany` | 分部/子公司浏览器检索（源 search_subcompany） |
+| `caizhilian.org.search-external` | 只读 | — | `search_external` | 外部人员浏览器检索（源 search_external） |
+| `caizhilian.org.search-position` | 只读 | — | `search_position` | 岗位浏览器检索（源 search_position） |
+| `caizhilian.org.search-role` | 只读 | — | `search_role` | 角色浏览器检索（源 search_role） |
+| `caizhilian.org.search-customer` | 只读 | — | `search_customer` | CRM 客户浏览器检索（源 search_customer） |
+| `caizhilian.org.search-customer-type` | 只读 | — | `search_customer_type` | CRM 客户类型字典检索（源 search_customer_type） |
+
+### user（1 条对外 operation）
+
+当前登录人
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.user.current` | 只读 | — | `fetch_current_user_info` | 获取当前登录人信息（employeeId / employeeName） |
+
+### tag（6 条对外 operation）
+
+标签
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.tag.search` | 只读 | — | `search_tags` | 检索标签（type=0 公共标签限定 document 模块，type=1 个人标签） |
+| `caizhilian.tag.list` | 只读 | — | `fetch_doc_tags` | 查询文档已打标签（公共 + 个人合并） |
+| `caizhilian.tag.add.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `add_doc_tag` | 为文档添加标签 |
+| `caizhilian.tag.remove.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `remove_doc_tag` | 移除文档标签 |
+
+### participant（5 条对外 operation）
+
+参与人
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.participant.list` | 只读 | — | `fetch_doc_participants` | 查询文档参与人列表 |
+| `caizhilian.participant.add.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `add_doc_participant` | 添加文档参与人 |
+| `caizhilian.participant.remove.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `remove_doc_participant` | 移除文档参与人 |
+
+### share（6 条对外 operation）
+
+文档共享
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.share.form` | 只读 | — | `fetch_doc_share_form` | 查询文档共享表单配置（对象类型 + 级联参数） |
+| `caizhilian.share.list` | 只读 | — | `fetch_doc_share_list` | 查询文档共享列表（含 download / can_delete） |
+| `caizhilian.share.add.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `add_doc_share` | 添加文档共享 |
+| `caizhilian.share.delete.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `delete_doc_share` | 删除文档共享 |
+
+### attachment（6 条对外 operation）
+
+附件
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.attachment.upload.prepare/apply` | prepare=写前回查，apply=上传写 | prepare → apply | `upload_attachment_to_doc` | 向文档上传附件 |
+| `caizhilian.attachment.replace.prepare/apply` | prepare=写前回查，apply=上传写 | prepare → apply | `replace_document_attachment` | 替换文档附件（reUpload，保留附件 ID） |
+| `caizhilian.attachment.download` | 本地落盘 | — | `download_doc_attachment` | 下载文档附件到本地（写本地磁盘，不改服务端） |
+| `caizhilian.attachment.download-as-pdf` | 本地落盘 | — | `download_doc_attachment_to_pdf` | 下载文档附件的 PDF 转换版本（写本地磁盘） |
+
+### cover（6 条对外 operation）
+
+封面
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.cover.upload.prepare/apply` | prepare=写前回查，apply=上传写 | prepare → apply | `upload_cover_image` | 上传封面图片，仅返回 file_id（不改文档） |
+| `caizhilian.cover.set.prepare/apply` | prepare=写前回查，apply=上传写 | prepare → apply | `set_doc_cover` | 上传图片并设为文档封面 |
+| `caizhilian.cover.remove.prepare/apply` | prepare=写前回查，apply=高风险写 | prepare → apply | `remove_doc_cover` | 移除文档封面 |
+
+### compare（6 条对外 operation）
+
+文档比对
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.compare.search-documents` | 只读 | — | `search_doc_compare_documents` | 文档比对：检索可比对文档 |
+| `caizhilian.compare.list-file-objects` | 只读 | — | `doc_compare_query_file_objects` | 文档比对：列出文档下可比对的文件对象 |
+| `caizhilian.compare.upload-file.prepare/apply` | prepare=写前回查，apply=上传写 | prepare → apply | `doc_compare_upload_file` | 文档比对：上传本地文件参与比对 |
+| `caizhilian.compare.submit.prepare/apply` | prepare=写前回查，apply=外部制品 | prepare → apply | `doc_compare_upload_compared` | 文档比对：提交左右文件生成比对链接（外部制品） |
+
+### system（1 条对外 operation）
+
+系统自检
+
+| Operation | 风险 | 确认链 | 源 operation | 说明 |
+| --- | --- | --- | --- | --- |
+| `caizhilian.system.health` | 只读 | — | `check_system_health` | 采知连接口连通性与登录态自检 |
+
+合计 87 条对外 operation，来自 60 个 canonical 操作（源 Skill 60 条操作规格中的写操作展开为 prepare/apply）。
+
+## 常用命令
+
+```text
+weaver-work-cli caizhilian schema
+weaver-work-cli caizhilian operations
+weaver-work-cli --json caizhilian health
+weaver-work-cli --json caizhilian search --keywords 季度报告 --page-size 10
+weaver-work-cli --json caizhilian get --doc-id 1234567890
+weaver-work-cli --json caizhilian run caizhilian.user.current
+weaver-work-cli --json caizhilian run caizhilian.org.search-user --input-json '{"keyword":"张三"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.query-by-name --input-json '{"folder_name":"财务","kb_type":"company"}'
+weaver-work-cli --json caizhilian run caizhilian.folder.get-settings --input-json '{"folder_id":"456"}'
+weaver-work-cli --json caizhilian run caizhilian.share.form --input-json '{"doc_id":"1234567890"}'
+weaver-work-cli --json caizhilian run caizhilian.tag.list --input-json '{"doc_id":"1234567890"}'
+weaver-work-cli --json caizhilian run caizhilian.participant.list --input-json '{"doc_id":"1234567890"}'
+weaver-work-cli --json caizhilian run caizhilian.compare.list-file-objects --input-json '{"doc_id":"1234567890"}'
+```
+
+写操作一律两段式：先 `prepare` 拿预览与 `continuation`，向用户摘要并取得明确确认后，再用**与 prepare 完全相同的入参**加 `--continuation TOKEN --yes` 调 `apply`。
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli --json caizhilian run caizhilian.document.create-markdown.prepare --input-json '{"name":"周报","folder_id":"456","folder_type":"company","file_path":"C:\\data\\weekly.md"}'
+weaver-work-cli --json caizhilian run caizhilian.document.create-markdown.apply --input-json '{"name":"周报","folder_id":"456","folder_type":"company","file_path":"C:\\data\\weekly.md"}' --continuation TOKEN --yes
+weaver-work-cli --json caizhilian run caizhilian.share.add.prepare --input-json '{"doc_id":"1234567890","obj_type":"resource","share_level":"1","obj_id":["789"]}'
+weaver-work-cli --json caizhilian run caizhilian.share.add.apply --input-json '{"doc_id":"1234567890","obj_type":"resource","share_level":"1","obj_id":["789"]}' --continuation TOKEN --yes
+weaver-work-cli --json caizhilian run caizhilian.attachment.download --input-json '{"doc_id":"1234567890","attachment_id":"888","save_path":"C:\\data\\out"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli --json caizhilian run caizhilian.document.create-markdown.prepare --input-json '{"name":"周报","folder_id":"456","folder_type":"company","file_path":"/tmp/data/weekly.md"}'
+weaver-work-cli --json caizhilian run caizhilian.document.create-markdown.apply --input-json '{"name":"周报","folder_id":"456","folder_type":"company","file_path":"/tmp/data/weekly.md"}' --continuation TOKEN --yes
+weaver-work-cli --json caizhilian run caizhilian.share.add.prepare --input-json '{"doc_id":"1234567890","obj_type":"resource","share_level":"1","obj_id":["789"]}'
+weaver-work-cli --json caizhilian run caizhilian.share.add.apply --input-json '{"doc_id":"1234567890","obj_type":"resource","share_level":"1","obj_id":["789"]}' --continuation TOKEN --yes
+weaver-work-cli --json caizhilian run caizhilian.attachment.download --input-json '{"doc_id":"1234567890","attachment_id":"888","save_path":"/tmp/data/out/"}'
+```
+
+## 行为约定
+
+- **入参严格校验**：`additionalProperties: false`，多传字段报 `validation/unknown_field`；出现 `__proto__` / `constructor` / `prototype` 报 `validation/forbidden_key`；ID 类字段是纯数字字符串（也接受数字），否则 `validation/id_invalid`。
+- **Python 语义兼容**：源脚本大量使用 `str(args.get(k) or "").strip()` 与 `get_nested_value`，CLI 侧直译为 `pyArgText` / `pyArgStripped` / `nestedValue`，保留「Python 假值 → 空串」的行为；`update_doc_field` 同时接受规范字段名与源 `arg_key`（`abstract` / `abstract_text` 等）。
+- **枚举拼写 1:1 沿用源接口**：权限相关键是 `deletePremisstion` / `downloadPremisstion` / `newCreateDocPremisstion` / `newCreateFolderPremisstion` / `settingPermission`（源拼写 `Premisstion`，不要改成 `Permission`）。
+- **根文件夹约定**：`folder_id` 100 = 系统、200 = 公共、300 = 个人；`folder_type` / `kb_type` 取 `company` / `privy` / `sys`。`folder.create` 在 `parent_type=privy` 时强制 `sequence=0`、`inherit_parent=false`。
+- **分页语义**：`has_next = 本页条数 >= page_size`；`page_no` / `page_size <= 0` 报 `validation/number_invalid`（源是静默归一，CLI 选择显式报错）。
+- **确认链**：票据有效期 10 分钟，绑定 baseUrl + 登录账号 + 目标 apply 操作名 + 入参指纹 + 请求体指纹（文件类还绑定 MD5 与大小）。相应报错为 `continuation_expired` / `continuation_context_mismatch` / `continuation_mismatch` / `continuation_args_changed` / `continuation_target_changed` / `plan_changed` / `file_changed`，一律重新 prepare。
+- **文件传输**：上传统一走 `preUploadCheck` → `module/upload`，命中 MD5 秒传时不真正传文件；下载文件名取响应头 `content-disposition`（已过滤路径穿越），同名文件按 `名称(1).扩展名` 自动改名，不覆盖。
+- **共享语义**：`share.add` 在服务端返回 `code=500 + status=true` 时判定为「已存在」，返回 `{ added: false, message }`，不算失败；其他业务失败抛 `api/business_error`。`participant.remove` 用 `share_entry_id` 而不是 `user_id`。
+- **标签语义**：`type=0` 公共标签（仅 document 可用）、`type=1` 个人标签；批量写操作按「公共组 + 个人组」两次请求提交，空组跳过。
+- **warnings 不得丢弃**：创建文档时的共享兜底覆盖、参与人重复、批量上传部分失败、替换完成通知失败等都通过 `warnings` 表达，Agent 必须原样转述。
+- **写结果不确定**：停止 → 最多一次只读回查 → 未生效则重新 prepare，禁止自动重放 `.apply`。
+
+## 未暴露能力（withheld）
+
+`caizhilian operations` 的 `withheldOperations` 给出名称与理由：
+
+| 名称 | 替代 |
+| --- | --- |
+| `caizhilian.system.list-systems` | `weaver-work-cli config list`、`weaver-work-cli e10 auth status`、`weaver-work-cli --json caizhilian health` |
+| `caizhilian.system.get-loaded-config` | `weaver-work-cli config list` |
+| `caizhilian.system.reload-config` | 无需替代（CLI 每次进程启动即读取框架配置） |
+| `caizhilian.system.switch-config` | `weaver-work-cli config set ...`、`weaver-work-cli e10 auth login --base-url <域名>` |
+
+源 Skill 目录内还打包了系统设置（备份/加密/附件全局设置/存储）、文件收集、文件上传等**与文档中心无关**的模块，未纳入本 CLI；需要时按 `weaver-e10-skill-maker` 单独生成模块。详见 `skills/weaver-e10-caizhilian/references/withheld.md`。
+
+## 与源 Skill 的已知偏差
+
+1:1 转换以「离线契约等价」为目标（相同入参产生相同请求体、相同响应归一结果、相同错误语义），以下 13 处为有意偏差：
+
+1. 源 `run_create_preamble` 中共享兜底会覆盖文件夹兜底，因此 `create-html` / `create-markdown` / `create-office` 不回填 `participant_ids` / `virtual_folder_ids`，改由 prepare 的 `droppedFallbackWarnings` 告警。
+2. `document.update-field` 以规范字段名 `value` 优先，同时兼容源 `arg_key`。
+3. 时间范围解析强制东八区（源用机器本地时间）。
+4. `document.replace-content` 的 `coordinate == 1` 语义：`1` / `true` 命中，字符串 `'1'` 不命中（与源一致）。
+5. `caizhilian.system.health` 的 `environment.provider` 固定为 `weaver-work-cli:e10-auth`；本地无登录态时抛 `authentication/session_unavailable`（源返回 `success=false`）。
+6. `share.add` 的「已存在」判定沿用源 `code=500 + status=true`，但对非「已存在」的业务失败比源更严格，直接抛 `api/business_error`。
+7. `folder.list-default-shares` 增加 `folder_id` 别名（源入参名是 `folderId`）。
+8. `folder.query-by-permission` 的 `page_no` / `page_size <= 0` 显式报错（源静默归一）。
+9. 标签元素 schema 更宽松，但保留源的「无有效标签」校验为 `validation/field_invalid`。
+10. `participant.add` / `participant.remove` 的 prepare 增加了源没有的只读回查（只告警、不阻断）。
+11. 下载类操作对显式 `null` 不复刻 Python 的 `str(None) == 'None'`（schema 已禁止 null）；`encodeURIComponent` 与 Python `quote(safe="")` 在 `!'()*` 上略有差异。
+12. `folder.query-by-permission` 的 `object_ids` 保持字符串原样提交（源按整数提交）：E10 对象 ID 是 19 位雪花号，超出 JS 安全整数范围（2^53），转 number 会静默丢精度，服务端按错误 ID 匹配只会返回空结果。
+13. 入口新增 `validation/number_out_of_range`：任何 operation 的入参里出现超出安全整数范围的整数（大 ID 用 JSON 数字传入）直接报错并提示改用字符串，源无此校验。
+
+## 新增模块
+
+本次补充了 6 个模块，覆盖了源 Skill 中被排除的系统设置与文件管理能力：
+
+| 模块 | CLI 操作 | 功能 |
+| --- | --- | --- |
+| 附件设置 | `caizhilian.setting-attach.*` | 上传最大、格式控制、批量下载等 11 项配置 |
+| 备份设置 | `caizhilian.setting-backup.*` | 备份开关、规则 CRUD、启停 |
+| 加解密设置 | `caizhilian.setting-encrypt.*` | 8 项加解密配置 |
+| 存储设置 | `caizhilian.setting-storage.*` | 存储实例与规则管理 |
+| 文件采集 | `caizhilian.file-collection.*` | FTP/SFTP 文件采集任务管理 |
+| 文件上传 | `caizhilian.file-upload.*` | 本地文件上传到文件服务 |
+
+详细用法参见各模块的 reference 文档。
+
+## 验证状态
+
+- 已通过：`tsc --noEmit`、`npm run build`、`caizhilian schema` / `caizhilian operations` 实际输出、`test/business/caizhilian-operations.test.ts`（24 项）与 `test/business/caizhilian-command.test.ts`（5 项）。
+- **未过检测器**：本次生成没有可用的 Skill 检测器（`validate_skill.py`），因此交付状态标注为「未过检」。
+- **真实 E10 端到端目前只覆盖 `folder.query-by-permission`**：2026-09-21 在真实租户验证了按权限反查（默认共享 / 文档权限 × 人员 / 部门），并修复了 `object_ids` 转 number 导致的精度丢失缺陷；创建、共享、上传、下载与比对链路仍为离线契约级（fake host），未在真实 E10 环境跑通。

package/docs/contract.md

@@ -0,0 +1,91 @@
+# 今承达合同管理 CLI
+
+来源目录：`泛微E10今承达合同管理`（源 Skill `weaver-e10-jinchengda`）。本模块把接口文档中可安全自动化的能力封装为 `weaver-work-cli contract` 命令，供 AI Agent 通过结构化 JSON 调用。
+
+源码位于 `src/shortcuts/contract`。命令注册、operation manifest 和业务执行逻辑分离；具体执行逻辑在 `src/shortcuts/contract/operations` 中按 operation class 维护。
+
+面向 Agent 的说明位于 `skills/weaver-e10-jinchengda`。入口 `SKILL.md` 只负责共享规则和 reference 路由；具体细节拆在 `skills/weaver-work-cli-jinchengda/references/`，与飞书 CLI 的业务 Skill 组织方式保持一致。
+
+## 公共前置
+
+先通过 E10 鉴权模块登录，并用 CLI 判断登录态：
+
+```text
+weaver-work-cli auth login --base-url "https://weapp.xxx.cn"
+weaver-work-cli auth status --no-check
+```
+
+每个合同业务请求由 CLI 托管：
+
+1. 读取当前 `weaver-work-cli auth` Profile 的 E10 会话。
+2. 请求只使用相对 `/api/...` 路径，完整地址和认证由会话提供。
+3. `userid` / `userId`（催办接口）由 CLI 从会话注入。
+
+Agent 不得在业务 JSON 中传 `userid`、`userId`、Cookie、ETEAMSID、Token 或内部控制字段（`sedit`、`dubboFlag`、`dubboToken`、`skipFlag`）。
+
+## Agent 入口
+
+优先使用 `contract run <operation>`：
+
+Windows PowerShell：
+
+```powershell
+weaver-work-cli contract schema
+weaver-work-cli --json contract run contract.type.tree
+weaver-work-cli --json contract run contract.workflow.query --input-json '{"workflowName":"销售合同起草","status":"1"}'
+```
+
+macOS/Linux（bash/zsh）：
+
+```bash
+weaver-work-cli contract schema
+weaver-work-cli --json contract run contract.type.tree
+weaver-work-cli --json contract run contract.workflow.query --input-json '{"workflowName":"销售合同起草","status":"1"}'
+```
+
+## operation 分组
+
+| 分组 | operation |
+|---|---|
+| 合同类型与模板 | `contract.type.tree`、`contract.template.tree`、`contract.template.list`、`contract.template.detail` |
+| 条款查询 | `contract.clause.tree`、`contract.clause.list`、`contract.clause.group.list`、`contract.clause.search`、`contract.clause.tags` |
+| 条款引用 | `contract.clause.reference.get`、`contract.clause.reference.save.prepare/apply` |
+| 签约主体 | `contract.subject.app`、`contract.subject.form`、`contract.subject.fields`、`contract.subject.options`、`contract.subject.query`、`contract.subject.create.prepare/apply` |
+| 流程解析 | `contract.workflow.query`、`contract.workflow.list`、`contract.workflow.form.info`（三段式：loadBaseParam → loadFrameParam → getFormLayout）、`contract.workflow.field.options` |
+| 流程写操作 | `contract.request.create.prepare/apply`、`contract.request.save.prepare/apply`、`contract.request.submit.prepare/apply`、`contract.request.supervise.prepare/apply` |
+| 流程状态 | `contract.request.status`、`contract.request.log` |
+
+完整字段与风险等级以 `weaver-work-cli contract schema` 为准。
+
+## 业务成功码适配
+
+源资料中各接口的成功码字段并不统一，适配层按路径分组判定，不凭 HTTP 200 判定业务成功：
+
+| 路径 | 成功判定 |
+|---|---|
+| `/api/ebd/**` | 顶层 `code = 0` |
+| `/api/ebuilder/form/obj/getObjsByTag`、`/api/bs/ebuilder/app/tags/getAppIds`、`/api/ebuilder/common/ds/fields`、`/api/ebuilder/common/ds/options` | 顶层 `code = 200` 且 `status` 不为 false |
+| `/api/ebuilder/form/dataset/v2/**` | `message.code = "0"` |
+| `/api/workflow/**` | `message.errcode = "0"`（`getFieldOption` 上游示例为 `200`，同样视为成功） |
+
+## 环境与 ID 约束
+
+- `appId`、`objId`、`formId`、`workflowId`、`nodeId`、人员/选项/业务数据 ID 均视为环境相关字符串，必须运行时解析。
+- 未找到就停止并提示用户配置 Tag 或确认名称，不使用标准环境 ID 兜底。
+- 同名多结果时展示候选请用户选择，不默认取第一条。
+
+## 写操作确认链
+
+- 写操作一律 `prepare -> apply`：`prepare` 返回脱敏 `preview` 与 `continuation`（有效期 10 分钟），`apply` 必须带 `continuation` 与 `confirm: true`。
+- 提交审批与催办需要与“创建并保存”分开的第二次确认。
+- 提交后回读 `contract.request.status`，`flowStatus.code` 为 1（审批中）或 3（已归档）才算生效。
+- 写请求超时或断线返回 `partial/write_uncertain`（退出码 11），禁止自动重放。
+- `submitRequest` 返回 `1200306` 时解析缺失字段补全后重试（最多 3 轮）；返回 `1200301` 时停止并诊断会话状态。
+
+## 暂未实现
+
+企业资信查询、企业变更、企业监控和撤回/退回流程在源资料中缺少接口路径、参数或确认契约，已列入 `withheldOperations`，详见 `skills/weaver-work-cli-jinchengda/references/contract-disabled-capabilities.md`。
+
+## 源资料指纹
+
+`skills/weaver-work-cli-jinchengda/references/source-manifest.json` 记录了源资料的 `sha256` 与聚合指纹，用于后续检测源资料更新；更新检测确认前不要覆盖已生成的 CLI 与 Skill。

package/docs/e10-auth.md

@@ -38,9 +38,9 @@ weaver-work-cli auth export-weaver-env
 环境变量推断当前宿主，最后回落为 `weaver-work-cli`。浏览器授权地址会同时携带
 `agent_type=<value>` 和 `from=<value>`，其中 `from` 用于 E10 授权确认页展示客户端名称。
 
-XiaoE 宿主环境中，`auth login` / `auth oidc` / `auth xiaoe` 会先尝试读取宿主 `xiaoeUserData/tokens.py`；脚本不可用（不存在、执行失败，或所用 Python 缺少 `requests` 等依赖）时，CLI 改用内置的原生等价实现读取 XiaoE 客户端本地会话（macOS `~/Library/Application Support/XiaoE/Robots/*/user_settings.json`，Windows `%LOCALAPPDATA%/XiaoE/Robots/*/user_settings.json`，或 `XIAOE_USER_TOKEN`）并换取 `eteamId`，该链路不依赖本机 Python 环境；仍没有可用凭证时，再从 `XIAOE_*` 环境变量读取当前域名对应的统一登录凭证。凭证可用时，CLI 直接保存登录态，保存的 `agentType` 固定为 `XiaoE`；凭证只返回 `eteamId` 时，会使用凭证中的域名或资料包默认域名 `https://www.e-cology.com.cn`；仍没有可用凭证时才考虑当前 profile 配置。业务命令在未显式指定 `--auth` / `--profile` 时，也会自动优先尝试 XiaoE 统一登录。XiaoE 凭证校验失败、当前域名不在支持范围内，或用户切换了访问域名时，`auth xiaoe` 会先反馈未拿到登录信息的原因，再自动降级到原浏览器 OAuth2.0 登录。
+XiaoE 宿主环境中，`auth login` / `auth oidc` / `auth xiaoe` 先使用平台注入的 `XIAOE_USER_TOKEN` + `XIAOE_DOMAIN` 换取 ETEAMSID（沙箱/Linux 环境唯一可用来源）；拿不到时再读宿主 `xiaoeUserData/tokens.py`；仍不可用时改用内置的原生等价实现读取桌面 XiaoE 客户端本地会话（macOS `~/Library/Application Support/XiaoE/Robots/<id>/user_settings.json`，Windows `%LOCALAPPDATA%/XiaoE/Robots/<id>/user_settings.json`），该链路不依赖本机 Python 环境；仍没有可用凭证时，再从 `WEAVER_XIAOE_*` 环境变量读取当前域名对应的统一登录凭证。宿主只注入 `XIAOE_DOMAIN` 等域名变量和 `XIAOE_USER_TOKEN` 凭证变量，不会注入 ETEAMSID 环境变量，CLI 也不读取 `XIAOE_ETEAMSID`。凭证可用时，CLI 直接保存登录态，保存的 `agentType` 固定为 `XiaoE`；凭证只返回 `eteamId` 时，会优先使用凭证中的域名或宿主注入的 `XIAOE_DOMAIN`（支持省略 `https://` 前缀），没有时才用资料包默认域名 `https://www.e-cology.com.cn`；仍没有可用凭证时才考虑当前 profile 配置。业务命令在未显式指定 `--auth` / `--profile` 时，也会自动优先尝试 XiaoE 统一登录。XiaoE 凭证校验失败、当前域名不在支持范围内，或用户切换了访问域名时，`auth xiaoe` 会先反馈未拿到登录信息的原因，再自动降级到原浏览器 OAuth2.0 登录。
 
-脚本链路按 `python3`、`/usr/bin/python3`、`python` 顺序探测可用解释器；可用 `XIAOE_TOKEN_SCRIPT_PYTHON` 指定解释器，用 `XIAOE_TOKEN_SCRIPT_PATH` 指定脚本路径。
+脚本链路按 `python3`、`/usr/bin/python3`、`python` 顺序探测可用解释器；可用 `WEAVER_XIAOE_TOKEN_SCRIPT_PYTHON` 指定解释器，用 `WEAVER_XIAOE_TOKEN_SCRIPT_PATH` 指定脚本路径（旧名 `XIAOE_TOKEN_SCRIPT_PYTHON` / `XIAOE_TOKEN_SCRIPT_PATH` 仍兼容）。`XIAOE_` 是平台保留前缀，本 CLI 的自定义变量统一使用 `WEAVER_XIAOE_*`。
 
 无法使用浏览器回调时，可以用 `auth set` 直接写入浏览器中复制到的
 `ETEAMSID`。命令会调用 `teamsCheck` 解析当前用户、租户和组织信息，并写入

package/docs/hrm.md

@@ -34,19 +34,29 @@ HRM 接口必须携带页面上下文 `Referer`（默认 `<baseUrl>/hrm/main`）
 
 **响应成功判定**：统一 `code=200`。`403`（接口开关未开启）抛 `api/permission_denied`，其余业务失败抛 `api/business_error`。
 
-**数据行位置**：
+**数据行位置（下表描述的是上游原始响应，不是 CLI 输出）**：
 
-| 接口类型 | 行字段 | 总数 |
+| 接口类型 | 行字段 | CLI `data.total` 的来源 |
 | --- | --- | --- |
-| 员工浏览 `employee.query` | `data.data` | `count/resource` 的 `data.total`（`data/resource` 的 `data.count` 恒为 0） |
-| 下属查询 `subordinate.mine` | `data.data` | `count/resource` 的 `data.total` |
-| 组织浏览 `org.query` | `data.data` | `data.total` |
-| 岗位浏览 `position.query` | `data.data` | `data.total` |
-| 岗位批量 `position.list` | `data.data` | `data.total` |
+| 员工浏览 `employee.query` | `data.data` | 本页行数（**不调 count 接口**，上游 `data.count` 恒为 0） |
+| 下属查询 `subordinate.mine` | `data.data` | 本页行数 |
+| 组织浏览 `org.query` | `data.data` | 上游 `data.total` |
+| 岗位浏览 `position.query` | `data.data` | 上游 `data.total` |
+| 岗位批量 `position.list` | `data.data` | 上游 `data.total`（自动翻页累加） |
 | 批量人员 `employee.batch` | `data.userList` | 行数 |
-| 下属按 id `subordinate.by-id` | `data.page.result` | `data.page.totalCount` |
+| 下属按 id `subordinate.by-id` | `data.page.result` | 上游 `data.page.totalCount`（**真实总数**，另附 `data.page.hasNext/totalPages`） |
 
-**详情接口**（`employee.detail`/`org.detail`/`position.detail`）返回单对象，CLI 附 `link`。
+CLI 已把上表差异归一化：**列表类统一输出 envelope 的 `data.rows` + `data.total`，分页参数在 `meta`（current/pageSize）**；不要把上游的 `data.data` / `data.page.result` 当作 CLI 输出路径。⚠️ 注意 `employee.query`/`subordinate.mine`/`dept.members` 的 `data.total` 是**本页行数**（想要真实总数只能按 `current` 翻页到 `rows.length < pageSize`），而 `org.query`/`position.*`/`subordinate.by-id` 的 total 才是上游真值。
+
+**详情接口**（`employee.detail`/`org.detail`/`position.detail`）返回单对象：上游 `WeaForm` 的业务字段位于其 `data.data`，CLI 会**展平上移一层**，因此 CLI 输出中业务字段**直接挂在 envelope 的 `data` 下，没有 `data.data` 嵌套**（`items`/`groups`/`layout` 等前端表单元数据已丢弃），并附 `link`。其中 `org.detail`/`position.detail` **只透出显式投影后的少量字段**：`org.detail` → `id/name/type/code/fullPath/status/parentName?/subcompanyName?/description?/remark?/link`（**不含 `employee_count`**）；`position.detail` → `id/name/code/parentName?/jobsetName?/jobsetTypeName?/grade?/link`（**不含 `fullName`/`department`**）。这两个接口都没有 `full` 开关。
+
+**`employee.detail` 默认投影**：完整卡片有 85 个顶层键（~5.3KB），其中大部分是登录/管理元数据（`password`/`last_android`/`hideFieldList`/`setting`/各 `*_admin`…）。默认只回 `DETAIL_CORE_FIELDS` 白名单的 26 个键（~1.2KB）：实体数组字段（`department`/`subcompany`/`position`/`personnel_status`/`jobsetid`/`jobset_level`/`location`）只留 `{id, name}`，人员数组字段（`superior`/`other_superior`/`assistant`）只留 `{id, name, statusCode, avatar}`，`avatar` 只留 1 个 `url`。需要完整卡片时传 `full: true`（该开关只影响 `employee.detail`；`org.detail`/`position.detail` 没有该开关，且它们已只透出上面列出的显式投影字段）。
+
+**「人员列表」默认投影**：`subordinate.mine` / `dept.members`（`formatMember` 行 366B）与 `subordinate.by-id`（原始行 960B，其中上游 `superior` 对象一项就占 485B）默认都走 `formatPersonBrief`——每行只回 `{id, name, link}`（~116~120B/行）。需要部门/岗位/电话/上级等列时传 `full: true`（`subordinate.mine`/`dept.members` 回 `formatMember` 行，`subordinate.by-id` 回 `formatSubordinateFull` 行）。
+
+**`employee.query` 默认投影**：默认走 `formatQueryRowBrief`——每行只回**人员信息** 6 键 `{id, name, department, position, statusCode, link}`（368B → 186B，省 49%）。裁掉的是：另两套 id（`userid` 登录信息 id / `cid` IM 联系人 id）、本接口恒为空串的 `mobile`、以及 `departmentId` + `deptLink`。传 `full: true` 回原来的 `formatMember` 完整行。
+
+**三套 id 口径**：`id` = 人员 id（驼峰 `userId` 同值；卡片链接 / `employee.detail` / `employee.batch.ids` / `subordinate.by-id` 只认它）；`userid` = 登录信息 id（登录账号场景）；`cid`/`imCid` = IM 联系人 id（IM 聊天 / 在线状态）。三者禁止混用。
 
 **长整型 id 一律按字符串传递**；**手机号已脱敏**（3 位前缀 + `****` + 末 4 位）。
 

package/docs/invoice.md

@@ -32,6 +32,8 @@ Windows PowerShell：
 ```powershell
 weaver-work-cli invoice schema
 weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
+weaver-work-cli --json invoice list --view summary
+weaver-work-cli --json invoice list --fields number,detailUrl
 ```
 
 macOS/Linux（bash/zsh）：
@@ -39,11 +41,13 @@ macOS/Linux（bash/zsh）：
 ```bash
 weaver-work-cli invoice schema
 weaver-work-cli --json invoice run invoice.list --input-json '{"page_size":10,"start_pos":0}'
+weaver-work-cli --json invoice list --view summary
+weaver-work-cli --json invoice list --fields number,detailUrl
 ```
 
 成功和失败都使用 JSON envelope。成功写 stdout；失败写 stderr，并设置非 0 退出码。
 
-当前输出层是完整 JSON 直接写 stdout，不提供飞书 CLI 的 `--jq`、`--format table/ndjson` 或通用 `--page-all`。Agent 使用时应默认小页读取和摘要渲染：列表先 `page_size=10`，按 `start_pos` 继续；回复只展示关键字段和数量，超长详情/OCR/调试 JSON 落本地文件后给路径。
+当前输出层把完整 JSON 直接写 stdout。0.1.17 起可用 `--view summary`（列表语义平表，仅 `invoice.list` / `invoice.enterprise.list` 支持）与 `--fields a,b.c`（点路径投影，所有 operation 可用）裁剪输出——两者互斥，只影响输出、不改变请求参数；仍不提供飞书 CLI 的 `--jq`、`--format table/ndjson` 或通用 `--page-all`。Agent 使用时应默认小页读取和摘要渲染：列表先 `page_size=10`，按 `start_pos` 继续；回复只展示关键字段和数量，超长详情/OCR/调试 JSON 落本地文件后给路径。
 
 ## Operation 目录
 

package/docs/meeting.md

@@ -36,7 +36,7 @@ weaver-work-cli meeting today                        # 今天会议（meeting.li
 ## 关键契约（源资料实测坑位）
 
 - 新建会议 `operateType=SUBMIT` + `id:""` → 正常状态；`ADD` 只生成草稿，勿用。
-- 冲突处理看接口返回 `cansub`：false=禁止提交（直接拒绝）；true=仅提醒（建议换时间/地点）；检测失败视为冲突。**绝不提供"强制新建"选项**。
+- 冲突处理看接口返回 `cansub`：false=禁止提交（直接拒绝，怎么都不允许）；true=仅提醒（如实告知并建议换时间/地点，**用户坚持时仍可继续提交**）；检测失败视为冲突（保守拒绝）。
 - 周期会议 `finishAt` 必填（仅 1=次数 / 2=日期，禁止 0）；`repeatDesc` 由 CLI 自动拼接。
 - 回执更新必须传回执记录 `id`（prepare 自动按 `memberId` 回查）；`attendStatus` 0/1/2。
 - 超 2^53 的 id 一律字符串传递。