一程 yicheng CLI
yicheng 是一程（Yicheng，自部署旅行 agent）的命令行客户端：查询行程/待办/素材箱/画像，并按令牌权限写入。零依赖，要求 Node 18+。成功输出 JSON 到 stdout（供解析分支）；失败输出一行中文说明到 stderr，退出码可判断。
接入检查（先做这个）
先探测凭证是否已配置：
yicheng whoami
- 输出账号 JSON → 已就绪。
- 提示缺少令牌或退出码 2 → 依次尝试：
yicheng login（弹出浏览器，用户登录并勾选权限确认后令牌自动保存到本机；CI 无桌面环境加YICHENG_NO_OPEN=1只打印链接）。用户不方便开网页时，让其在网页「设置 → CLI 访问令牌」生成 PAT（明文只显示一次）并交给你，然后yicheng set token <令牌>。 - 退出码 4 且 stderr 含 401 → 令牌已吊销/输错，请用户重新 login 或换令牌。
服务地址有内置默认（https://yicheng.online）；自部署才需要 yicheng set url <URL>。优先级：--url/--token 参数 > YICHENG_URL/YICHENG_TOKEN 环境变量 > 本机配置。未安装时先装：npm install -g @wuchunlin/yicheng，或免安装 curl -O https://yicheng.online/cli/yicheng.mjs 后用 node yicheng.mjs 代替。
命令
查询（任何有效令牌按权限可用）：
yicheng trips # 行程清单，拿 id
yicheng trip <id> # 整份详情（版本链 + 成员 + 待办）
yicheng trip <id> --day 2 # 只出第 2 天
yicheng trip <id> --items # 只出待办/贴士/待计划（含条目 id）
yicheng todo [--date YYYY-MM-DD] # 待办看板：最近行程待办 + 当日日程
yicheng notes [--collection ID] [--source xhs|clip|text] [--q S] [--trip ID] [--limit N]
# 素材箱清单（标题/摘要/来源，不含全文）
yicheng note <id> # 素材详情（全文）
yicheng collections # 素材集清单
yicheng profile # 旅行偏好事实
写入（令牌须勾选对应权限项；删除必须显式 --yes）：
yicheng trip-create <file|-> [--title S] # 行程 JSON（导出文件或裸 {destination, days}）建新行程
yicheng trip-update <id> --title 新标题 # 改名
yicheng trip-update <id> --file <file|-> # 存新版本（默认基于最新版）
yicheng trip-delete <id> --yes # 删行程（不可恢复）
yicheng todo-add <tripId> --title "订高铁票" [--note S] [--due S] [--tags a,b] [--kind todo|tip|parked]
yicheng todo-update <tripId> <itemId> --note 新内容 # 只传要改的字段，其余保留；空串清除
yicheng todo-done <tripId> <itemId> [--undo] # 勾选/取消完成
yicheng todo-delete <tripId> <itemId> --yes # 删条目（不可恢复）
yicheng note-add --body "断桥残雪要早去" [--title S] [--link URL] [--tags a,b] [--trip ID] [--collection ID]
# 收素材：只给 --link 则服务端解析（小红书/网页）
yicheng note-update <id> [--title S] [--body S] [--trip ID] [--collection ID] # 空串清除归属
yicheng note-delete <id> --yes # 删素材（不可恢复）
yicheng collection-create <name> # 建素材集（--collection 归集用）
条目 id 从 yicheng trip <id> --items 的输出里取；素材 id 从 yicheng notes 里取。
两种链接：分享（报告）与邀请（协同编辑）
trip-share 分享链接 |
trip-invite 邀请链接 |
|
|---|---|---|
| 用途 | 把行程当报告发出去给人看 | 让旅伴加入一起编辑 |
| 内容 | 生成时冻结的只读快照 | 行程最新内容（加入即成员） |
| 访问 | 任何人凭链接免登录只读 | 未登录 = 只读预览；登录后一键加入，可协同编辑 |
| 失效 | trip-unshare <id> <tokenHash> --yes |
trip-uninvite <id> <tokenHash> --yes、到期（默认 7 天）或达 --max-uses |
yicheng trip-share <id> [--list] # {"ok":true,"url":"…/chat#/share/<token>"}，直接发给用户
yicheng trip-invite <id> [--max-uses N] [--expires-days N] [--list] # url 形如 …/chat#/join/<token>
链接一经泄露任何人都可访问，不用时凭 --list 里的 tokenHash 撤销。
打开行程网页
行程深链只在 /chat 页面生效（落在首页不处理）：<服务地址>/chat#/t/<tripId>（也认 #/trip/<id>）。用户想在浏览器里看行程时：
- 拿 id：
yicheng trips。 - 定位服务地址：
yicheng set（无参数）输出本机配置的 url，为 null 时即内置默认 https://yicheng.online（与命令相同的优先级）。 - 打开：
open "https://yicheng.online/chat#/t/<tripId>"（macOS；Linux 用 xdg-open，Windows 用start ""）。不便执行时就把完整链接贴给用户。
注意：
- 打开的浏览器须已有该账号的登录会话，否则落在登录页——CLI 令牌只是 API 凭证，不能当网页 cookie 用。
- 要给未登录的人看，用
yicheng trip-share <id>生成分享链接（免登录只读报告）；要邀人共同编辑，用yicheng trip-invite <id>。两者用途差异见上节，别混用。
硬规则
- 删除前先向用户确认，拿到明确同意后再执行；命令层面也必须带
--yes，否则退出码 2 拒绝执行。 - 令牌是用户凭证：不要把令牌明文写进对话回复、代码或提交；用户粘贴令牌时只用它配置，不复述。
- 权限按十个独立项授控（行程/待办/素材各自的读取、创建更新、删除，加上画像读取），服务端逐项校验。403 且 stderr 列出「缺少权限：xxx」时，告诉用户所缺权限项，引导
yicheng login重新授权或在网页重建令牌勾选——不要反复重试同一命令。 trip-update --file遇 409（他人更新过）时，让用户决定：加--base-version N指定基准重试，或先yicheng trip <id>看最新内容。- 连续手动保存会折版本（版本号不变、内容就地更新），不要把版本数当编辑次数。
输出与退出码（按此分支）
- 0 成功（stdout 是 JSON，用 JSON.parse 解析后再读字段）；
- 2 用法错误（未知命令/缺参数/缺
--yes）——修正命令，不要改权限； - 3 网络失败——检查服务地址或网络，可原样重试一次；
- 4 HTTP 错误——401 令牌失效（请用户重新授权）；403 权限不足（见硬规则）；404 资源不存在或无权访问（先
yicheng trips核对 id）。
典型工作流
用户说「帮我在青岛行程里加一条待办，明天出发前买防晒」：
yicheng trips # 找到青岛行程 id
yicheng todo-add <tripId> --title "买防晒" --due 明天出发前
用户说「把这条攻略存到一程，回头去杭州翻出来看」：
yicheng note-add --body "<攻略正文>" --tags 杭州 # 或只给 --link 让服务端解析小红书/网页
yicheng notes --q 杭州 # 之后检索
用户说「把行程发给我妈看看」→ trip-share（免登录只读）；「拉我朋友一起改行程」→ trip-invite。
用户给了一份行程 JSON 要导入：
# 把 JSON 原样存成临时文件（不要在 shell 里内联中文 JSON）
yicheng trip-create /tmp/trip.json --title "青岛三日"
改完内容用 --pretty 给用户看结果；给 agent 消费时保持默认紧凑输出。
