weaver-work-cli 0.1.0 → 0.1.2

package/skills/weaver-work-cli-shared/references/e10-auth-and-session.md

@@ -13,6 +13,12 @@ weaver-work-cli auth whoami
 
 `--no-check` 只读取本地登录态；需要实际验证服务端可用性时使用业务命令或明确带 live 校验的命令。
 
+## 认证隔离与禁止探查旧目录
+
+`weaver-work-cli auth root` 是唯一用于确认本 CLI 认证根目录的命令；默认根目录是 `~/.weaver-work-cli/e10`。Agent 不得因为历史兼容信息去读取、列出或 `cat` `~/.e10-cli`、`/Users/<user>/.e10-cli`、`e10-login` / `e10-cli` 的 auth、config 或 Keychain 数据。
+
+登录态判断只允许通过 `weaver-work-cli auth status --no-check`、`weaver-work-cli auth profile list/current`、`weaver-work-cli doctor --e10` 和业务命令返回的 JSON 错误完成。只有用户明确提供外部 auth 文件路径时，才可按用户要求使用 `--auth <path>` 或 `E10_AUTH_PATH`；不能主动搜索旧认证目录。
+
 ## 未登录 / 登录失效：必须先向用户提问登录域名，再登录
 
 业务命令依赖 E10 登录态。出现以下任一情况即判定为未登录或登录失效：
@@ -27,6 +33,7 @@ weaver-work-cli auth whoami
 - 使用示例占位域名（如 `https://weapp.xxx.cn`）或自行猜测域名执行登录
 - 未向用户确认登录域名前，反复重试业务命令
 - 要求用户提供 Cookie、ETEAMSID、业务 Token（见安全边界）
+- 读取、列出或解析 `~/.e10-cli`、`/Users/<user>/.e10-cli`、`e10-login` / `e10-cli` 的历史 auth、config 或 Keychain 数据
 
 **正确流程（按序执行，缺一不可）：**
 
@@ -80,4 +87,4 @@ weaver-work-cli --profile <name> auth status --no-check
 
 ## 安全边界
 
-Agent 不要要求用户贴 Cookie、ETEAMSID、业务 Token、app key 或 app secret。业务 Skill 只负责调用 CLI；登录态读取、Cookie 拼接、业务 Token 获取和 HTTP header 注入都由 `weaver-work-cli` 内部完成。
+Agent 不要要求用户贴 Cookie、ETEAMSID、业务 Token、app key 或 app secret，也不要直接读取用户机器上的 auth、config 或 Keychain 数据。业务 Skill 只负责调用 CLI；登录态读取、Cookie 拼接、业务 Token 获取和 HTTP header 注入都由 `weaver-work-cli` 内部完成。

package/skills/weaver-work-cli-shared/references/json-output-contract.md

@@ -59,3 +59,28 @@
 | `11` | 部分完成或结果不确定 |
 
 `retryable=true` 只表示读操作或准备阶段可能可以重试；写入请求已经发出后，遇到 `partial/write_uncertain` 必须停止并交给用户判断。
+
+## 大结果渲染与提效规则
+
+当前 `weaver-work-cli` 输出层是轻量封装：JSON 模式把完整结果写 stdout，文本模式写人类可读文本；不像飞书 CLI 已内置 `--format table/pretty/ndjson`、`--jq` 或通用 `--page-all`。Agent 因此必须在调用和回复阶段主动控量，避免把超长接口响应原样渲染给用户。
+
+### 调用前控量
+
+- 列表类 operation 默认先取小页：优先 `page_size=10`，需要更多结果时再按用户目标递增，通常不要超过 `20`。
+- 用户只想定位一个对象时，用筛选字段缩小范围；已有 `fid`、`number`、文件路径或 continuation 时直达对应 operation，不要先拉全量列表。
+- 用户说“全部 / 全量 / 统计”时，先说明会分页读取；每页读取后只保留任务所需字段和去重键，避免在上下文里累计完整原始响应。
+- 有 `hasMore`、`start_pos`、`page_token`、`next_page_token` 等分页字段时，用它们继续翻页；没有明确分页信号时不要无界循环。
+
+### 回复时渲染
+
+- 不要把完整 stdout JSON 直接粘给用户。优先输出结论、命中数量、关键字段、下一页/剩余数据提示和必要的文件路径。
+- 列表结果只展示最相关的前 `10` 条；如果用户要求更多，分批展示并说明还可以继续读取。
+- 详情结果只展示与用户问题相关的字段。发票类详情通常优先展示 `fid`、号码/代码、购销方、金额、日期、查验/报销状态和附件摘要。
+- 超长文本、大数组、OCR 原文、逐项明细或调试需要的完整 JSON，优先写入本地文件再给路径；不要在对话里展开。可用 shell 重定向保存完整 stdout，或业务 operation 暴露 `output` 参数时使用其文件输出。
+- 如果为了调试必须引用原始 envelope，只截取必要字段：`ok`、`operation`、`meta`、`warnings`、`error` 或 `data` 的相关子树。
+
+### 参考飞书 CLI 的实践
+
+- 飞书 CLI 用 `--format json` 保留机器可读 envelope，用 `pretty/table/ndjson/csv` 降低人读成本；本 CLI 目前主要依赖 `--json` envelope，因此 Agent 回复时承担 pretty/table 摘要职责。
+- 飞书 CLI 的分页实践是显式页预算（如 `--page-limit`）和页间延迟；本 CLI 业务 operation 应使用自身 schema 中的 `page_size/start_pos` 等字段模拟同样的预算控制。
+- 飞书 CLI 对大产物倾向返回 artifact 文件路径；本 CLI 遇到下载、导出、OCR 或超长 JSON 时也应优先落盘并只向用户展示路径和摘要。

package/skills/weaver-work-cli-shared/references/weaver-work-cli-installation.md

@@ -55,7 +55,19 @@ weaver-work-cli skills install invoice
 ```
 
 该命令会同时安装 `weaver-work-cli-shared` 和 `weaver-work-cli-invoice` 到
-`$CODEX_HOME/skills`；未设置 `CODEX_HOME` 时使用 `~/.codex/skills`。
+`$CODEX_HOME/skills`；未设置 `CODEX_HOME` 时使用 `~/.codex/skills`。默认目标
+面向 Codex CLI；WorkBuddy 等桌面 Agent 的用户级 Skill 目录不是默认目标，需
+显式指定后再安装：
+
+```bash
+weaver-work-cli skills install invoice --target-dir ~/.workbuddy/skills
+```
+
+`skills install` 是拷贝语义，装出的是真实副本，不与源目录联动。目标目录里
+已有旧条目（旧副本或软链）时不能直接覆盖：目标是软链会报
+`ERR_FS_CP_DIR_TO_NON_DIR`，先 `rm` 断链再安装；覆盖安装不会清理目标里已
+不存在的旧文件。安装只是文件拷贝，不需要 E10 登录；Agent 需新会话或重载
+Skill 后才读取新内容。完整安装/升级流程见仓库 `docs/agent-skill-install.md`。
 
 交付给 Agent 的 Skill ZIP 不内置运行时，只声明依赖本机可用的 `weaver-work-cli`
 bin。ZIP 主要用于平台导入、离线分发或版本归档，不应作为普通用户的必经安装步骤。