netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/resources/skills/netizen-user-guide/references/user-guide.md

@@ -0,0 +1,842 @@
+# Netizen 飞书用户手册
+
+Netizen 把飞书单聊、群聊主线和话题接入原生 Codex。飞书负责消息、卡片和会话入口；任务执行、原生 Thread、Turn、历史、工具、Skills、MCP、权限与 sandbox 仍由 Codex 管理。
+
+本手册解释稳定的使用语义，是 `/help` 的自然语言补充。当前实例实际开放的命令以运行时 `/help` 为准；当前会话和任务状态以 `/status` 为准。
+
+按任务查阅：
+
+- 首次使用：[快速开始](#快速开始)、[核心心智模型](#核心心智模型)。
+- 查找操作：[完整命令索引](#完整命令索引)、[会话与 Project 管理](#会话与-project-管理)。
+- 提交和接收内容：[消息、引用与图片](#发送消息引用与图片)、[回答 Codex 的问题](#回答-codex-的问题)、[本轮文件](#查看和发送本轮文件)。
+- 持续或并行工作：[定时任务](#定时任务)、[Side 临时话题](#side-临时话题)、[Goal](#goal)。
+- 管理和排查：[Admin Web](#admin-web)、[状态与停止](#状态压缩与停止)、[常见问题](#常见问题)。
+- 原生能力：[Codex Skills](#codex-skills)、[与 Codex App/CLI 的差异](#与-codex-appcli-的差异)。
+
+## 快速开始
+
+请先确认部署者已完成飞书应用授权、发布与可用范围设置，群聊还需加入机器人。如果没有可选
+Project，先通过 `/settings` 登记已有工作目录或创建项目并启用，再开始下面的步骤。
+
+1. 发送 `/new`，在卡片中选择项目。不确定模型配置时可选择“继承 Codex”，也可选择
+   Model（模型）、Effort（思考强度）和 Speed（速度）；过程卡和结束时 @ 提醒默认开启，执行中表情闪烁
+   默认关闭，可分别调整。
+   群聊和群话题还可选择 @ 时读取的消息范围。`/new` 不接受参数。
+2. 创建成功后直接发送任务，例如“梳理这个项目的结构”。创建会话本身不会启动任务。
+3. 普通任务或 Goal 执行中继续发送消息，会补充到当前正在执行的 Turn，不会排队成下一轮；
+   恰好完成或换轮时会提示重发，启动、停止、收尾或压缩期间会拒绝普通消息。
+4. 用 `/status` 查看当前会话、任务、原生执行步骤和上下文窗口；用 `/sessions` 查看同一聊天或
+   话题中的其他会话，并可在卡片中直接将其设为当前。
+5. 用 `/help` 查看当前实例此刻开放的命令。
+
+如果当前聊天已有可用的[会话默认配置](#默认会话配置与自动创建)，还没有当前会话时可以
+直接发送任务：机器人会在消息所在主线或话题创建会话并处理这条任务，无需先发 `/new`。
+已有当前会话时继续使用它，不再读取默认配置；`/new` 始终保留原有手动创建行为。
+
+没有匹配的默认配置时，机器人会给出原有下一步：没有已启用项目时先去 `/settings`，有
+项目时通过 `/new` 创建会话；当前聊天或话题已有会话记录时，还会提示 `/sessions` 和
+`/sessions archived` 查找并切换或恢复。默认配置不可用时会先说明原因，再给出这些提示。
+**被拦下的任务尚未执行，准备好会话后请重新发送。** 系统不会自动创建项目或重放任务。
+
+`/help` 顶部提供快速开始，命令按开始与设置、任务操作、会话管理分组。未知命令会提示
+查看帮助；误用 `/project` 或 `/projects` 会指向实际项目管理入口 `/settings`，不会
+执行项目操作。命令格式或参数错误会给出用法提示；`/new` 仍不接受任何参数。
+
+群聊主线和群话题中，每一条触发机器人的消息都必须重新 `@机器人`。单聊以及单聊中的
+话题无需 `@`。即使选择“自动带上期间的群聊讨论”，未 @ 的消息也只可能在下一次 @ 时
+作为背景进入 Codex，不会让机器人自动响应。
+
+同群其他机器人也可以通过真实 `@Netizen` 提交任务或补充正在执行的任务，发送者仍标注
+为机器人。飞书应用需开通并发布 `im:message.group_at_msg.include_bot:readonly` 权限；
+CLI setup 默认申请并检查此权限；已有应用缺失时，由部署者在 setup 中完成补权，
+Admin 不执行授权或程序升级。机器人的未 @ 消息不会自动加入“期间的群聊讨论”。
+
+## 完整命令索引
+
+以下是普通会话的操作索引；命令的前提、限制和后果见对应章节。每条消息只能包含一个
+control 或一个 prompt，不能串联多个命令。群聊中的命令同样需要 `@机器人`。
+
+| 输入 | 用途与重要前提 | 完整说明 |
+| --- | --- | --- |
+| 普通文本 | 空闲时开始任务；运行中补充当前任务，不排队 | [Turn 与 steer](#turnsteer-与排队) |
+| `//...` | 将字面 `/...` 作为普通任务文本发送 | [文本与斜杠](#普通文本和斜杠) |
+| `/new` | 用卡片选择 Project 并新建当前会话，不接受参数 | [新建会话](#新建与配置-project) |
+| `/defaults` | 用一张表单查看、保存或删除当前聊天的会话默认配置，不接受参数 | [默认配置](#默认会话配置与自动创建) |
+| `/settings` | 登记、创建、启用或停用 Project | [Project 管理](#新建与配置-project) |
+| `/config` | 修改当前空闲会话的模型、思考强度、速度、任务反馈和群聊消息范围，后续新任务生效 | [会话设置](#session-settings) |
+| `/sessions`、`/threads` | 列出当前聊天或话题的会话，切换或按行管理 | [查找与切换](#查找切换和命名会话) |
+| `/sessions archived` | 查看归档会话，恢复或经确认永久删除 | [归档管理](#归档恢复和删除) |
+| `/resume <短 ID>` | 切换当前 Scope 的普通会话，不停止其他会话的任务 | [查找与切换](#查找切换和命名会话) |
+| `/rename [名称]` | 重命名当前原生 Thread；省略名称打开卡片 | [命名会话](#查找切换和命名会话) |
+| `/compact` | 压缩当前空闲普通会话的上下文 | [压缩说明](#compact) |
+| `/release` | 取消当前空闲会话的本连接订阅，保留历史；不保证立即释放 writer | [订阅释放](#查找切换和命名会话) |
+| `/archive` | 确认后归档当前会话，保留历史并清空当前指针 | [归档与恢复](#归档恢复和删除) |
+| `/unarchive <短 ID>` | 恢复归档会话并切换到它 | [归档与恢复](#归档恢复和删除) |
+| `/delete` | 二次确认后永久删除当前会话；已有原生历史时会级联删除其子任务 | [删除后果](#归档恢复和删除) |
+| `/status` | 查看会话、原生任务步骤、上下文窗口和配置来源 | [状态快照](#status) |
+| `/stop` | 中断当前任务；Goal 先暂停，不保证所有工具进程退出 | [停止语义](#stop) |
+| `/side [首轮问题]` | 从已有历史创建临时分支话题，与 Parent 共享项目目录 | [Side](#side-临时话题) |
+| `/side close` | 在 Side 话题内结束临时会话 | [Side](#side-临时话题) |
+| `/goal [目标]` | 查看或启动持续目标 | [Goal](#goal) |
+| `/goal pause`、`/goal resume`、`/goal clear` | 暂停、恢复或显式结束当前 Goal | [Goal](#goal) |
+| `/cron` | 管理定时计划；暂停计划不停止已认领的执行 | [定时任务](#定时任务) |
+| `/admin` | 返回当前实例已绑定的管理地址与根目录；无需 Project 或当前会话 | [Admin Web](#admin-web) |
+| `$skill-name ...` | 在普通消息开头显式调用一个或多个 Codex Skills | [Skills](#codex-skills) |
+| `/help`、`/` | 查看当前实例开放的帮助 | [能力差异](#与-codex-appcli-的差异) |
+
+`/model`、`/effort`、`/fast`
+使用 `/new` 或 `/config` 替代；查询可用 Skill 直接用自然语言，不提供 `/skills`。
+`/plan`、`/apps`、`$app` 及 CLI/App 宿主命令的限制见[能力差异](#与-codex-appcli-的差异)。
+Side 仅接受其[命令白名单](#side-临时话题)，不能把上表所有普通会话操作用于 Side。
+
+## 核心心智模型
+
+### Scope、会话与 Project
+
+- 一个普通单聊、群聊主线或普通话题各自形成一个 Scope。每个 Scope 可以有多个会话，但同一时刻只有一个当前会话。
+- 会话必须绑定一个已登记且启用的 Project，也就是 Codex 实际工作的目录；Netizen 不使用
+  实例或服务工作目录作为默认兜底。
+- `/new` 只创建并切换到一个 Lazy 会话；首条真实任务才创建原生 Thread。
+- 没有当前会话时，可用的聊天默认配置允许普通任务消息自动创建会话并执行。主线与各话题
+  共用所属聊天的创建默认值，但各有独立的当前会话和上下文。
+- 原生 Thread 和历史由 Codex 保存，能够在 Codex App/CLI 中继续使用。CLI/App 中新增的消息不会自动回填到飞书。
+- 每条真实任务或 steer 都会把当前飞书消息的公开发送者信息交给 Codex，并随原生输入进入
+  Thread 历史。它只说明请求来源，不授予权限、任务所有权或更高指令优先级。Channel SDK
+  会从当前 chat 成员名单补全真实显示名；解析失败时本条消息不会执行，并会提示管理员为
+  飞书应用开通 `im:chat.members:read`、发布应用版本后重试。发送者归属 ID 只保留当前
+  应用内的 `open_id`，不会在 sender attribution 中加入 `union_id` 或租户级 `user_id`。
+- Netizen 只在内存跟踪本进程实际打开的 Thread 订阅。当前会话空闲十五分钟后自动取消
+  当前连接订阅；切换到其他会话后，旧会话一旦空闲就立即尝试取消。没有会话数量上限或
+  LRU，服务重启不会为这项空闲释放策略扫描全部历史、resume 会话或重建旧订阅 timer。
+- 不同会话或 Side 可以并发，但同一 Project 使用同一个真实目录，文件改动会互相可见。并发修改同一文件时应由用户自行协调。
+- 飞书应用可用范围和群成员资格决定谁能使用机器人；Netizen 不另设用户、群或角色
+  白名单。能向机器人发送有效消息的参与者可以管理所在 Scope 的会话或当前 Side，
+  不按会话创建者划分权限。各参与者共用部署服务账号的 Codex 工具与文件访问能力；
+  应由部署者把应用限制在受信用户和群范围内。Admin Web 使用另一套独立管理员凭据。
+
+### Turn、steer 与排队
+
+- 当前会话空闲时，普通消息开始一个新 Turn。
+- 当前 Turn 正在运行时，普通消息固定 steer 这个精确 Turn：它用于补充条件、纠正方向或追加要求。
+- 若 steer 恰好碰上 Turn 已结束，本条消息不会执行；看到提示后需要重新发送。
+- Netizen 不保存 prompt queue，不会把运行中的新消息悄悄排成下一轮，也不会把多条消息合并成一个 prompt。
+- `completed`、`interrupted` 和 `failed` 都只结束当前 Turn；即使本轮失败，Thread、历史和
+  Binding 仍保留，下一条消息可以在同一 Thread 开始新 Turn，不必为保留上下文而换会话。
+- 若暂时无法确认 exact Turn 状态，Netizen 只做一次最多 5 秒、最多三次原生 I/O 的
+  短恢复，其中最多 resume 一次。恢复 exact `inProgress` 就继续正常无时限轮询和 steer；
+  确认 terminal 就交付结果。仍不可验证时显示 `turn-observation-unavailable`，保留
+  exact 槽但停止自动 I/O，只隔离这个 Binding。`/sessions` 会提供一次有界重新检查、
+  停止、归档和删除；归档/删除不要求 Turn 观测先恢复。已确认 terminal 后的最终文本
+  读取失败也不会重新进入恢复。
+- 若确实想开始独立任务，应等待当前 Turn 结束、先 `/stop`，或切换/新建另一个会话。不同 Binding 可以并发。
+
+### 飞书中的运行反馈
+
+- 每个普通会话有三个独立的任务反馈选项，可在 `/new` 创建时或空闲时通过 `/config`
+  修改；新建时 Progress Card 和「结束时 @ 提醒」默认开启，Reaction Pulse 默认关闭。
+  升级后的已有会话默认开启结束提及，原表情/进度卡选择保留。
+  三项都关闭时仍会显示稀疏的生命周期表情，但没有 `THINKING` 闪烁、进度卡或结束提及，最终结果
+  仍会正常回复。
+- 普通或 Side Turn 在 accepted 后始终在原任务消息上尽力使用 `Typing`；steer 成功后在
+  steer 消息上使用 `OnIt`，原任务消息仍是运行状态锚点。完成、失败或中断时先使用
+  相应终态表情，再清理运行态表情。`OnIt` 失败时，已成功的 steer 会回退文字确认。
+- Reaction Pulse 开启后，执行中还会低频显示/隐藏 `THINKING`；关闭只停止这个动态闪烁。
+- Progress Card 开启后，普通或 Side Turn 被接受时回复一张运行卡；Goal 始终使用一张组合卡，
+  开启该选项时在卡中增加过程区。过程区在运行中展开，只按
+  当前状态、最近四条完成的进展、最近八条操作、子任务聚合与原生 checklist 的变化更新
+  同一张卡。最近进展和操作使用显示到分钟的原生事件时间，并由每位飞书查看者的客户端按本地
+  时区与语言显示，进展正文直接跟在时间分隔符 `·` 后。读取、列举和搜索操作可显示原生路径、
+  关键词和范围；无法从原生分类中取得对象信息的命令直接显示命令预览，失败命令可附带原生
+  非零退出码。文件修改显示路径和
+  变更类型，网页操作显示查询或链接，MCP/dynamic tool 继续显示原生工具名。
+  操作预览最多 120 字符，工具名不截断；文件和多查询最多预览前三项。每条进展文字最多
+  160 字符，保留普通路径、链接、邮箱和代码片段，明确凭据仍会过滤。不会根据命令名猜测
+  操作目的，也不展示工具参数/结果、命令
+  输出、server 或内部 reasoning，不生成耗时、完成百分比或 ETA。终态会在同一
+  卡片折叠过程并显示最终回答和
+  可用的本轮文件，文件翻页后仍保留折叠过程。结束时更新原卡失败，会在 5 秒内最多尝试
+  3 次；仍失败时会另发结果卡或文本，旧卡可能停留在最后一次成功更新的状态。
+  新话题模式的定时首轮已尝试投递后不另发第二份结果；原会话模式沿用普通消息规则。
+- 「结束时 @ 提醒」开启时，任务结束 @ 本轮任务发起人，执行中追加消息
+  不改变提醒对象。已有进度卡或 Goal 卡更新完成后，另发一条引用结果卡的 @ 提醒；
+  普通私聊和群主线使用普通引用回复，不创建话题，已有话题则在原话题内发送新提醒。
+  Goal 关闭进度卡后仍使用 Goal 卡，所以结束提醒不受进度开关影响。新发送的最终文本、
+  文件卡或 Goal 卡直接在回复内 @，不额外发提醒。可确认的执行失败也提及；主动停止、
+  中断和状态未知时不提及。Goal 在整项任务完成或因阻塞、额度/预算限制结束自动执行时提及一次，
+  不逐个内部轮次提及，主动暂停不提及。文件翻页和后续卡片控制重绘不再次加入 @。
+  若过程卡不可用而另发最终回复，就直接在这条新回复中 @，不额外造卡或再发提醒。
+  Goal 正文过长而另行回复时也相同。提醒发送失败或投递结果未知时，不换位置
+  或反复补发 @；已经尝试过 @ 的新回复投递失败后，后续回退不再提及。
+  当前 Side 执行错误可能
+  无法确认终态，因此不会提醒；富文本被平台拒绝并降级成纯文本时，也可能丢失真实 @。
+  真实 @ 的客户端通知效果仍需实测确认，不能仅凭卡片更新成功保证收到通知。
+- 三项可以独立开启。reaction/card 展示失败不会改变 Codex Turn；Progress
+  Card 初始、过程或终态更新失败时，最终结果沿用原有回复方式。
+- Progress Card 关闭时严格保持普通或 Side Turn 原有终态：无文件时使用富文本/静态文本回复，
+  有文件时最终文本和“本轮文件”合成完成卡。Goal 卡本身始终存在，关闭只是不加入
+  Activity 模块；Lifecycle Reaction 仍不作用于 Goal。Side 使用创建时冻结的 Parent 选项，
+  压缩不使用这些选项。系统定时输入新建的任务不 @；追加已有任务不改变原发起人的
+  提醒。后续人类消息发起的任务正常使用结束提及设置。
+
+## 发送消息、引用与图片
+
+### 普通文本和斜杠
+
+- 直接发送普通文本即可开始 Turn 或 steer。
+- 群内不同参与者依次发消息时，Codex 会分别看到每条当前消息的发送者；任务的运行反馈和
+  最终回复仍锚定原任务消息，不会因为后来有人 steer 就迁移。
+- 若收到“无法获取当前消息发送者姓名”，管理员需要在飞书开发者后台开通
+  `im:chat.members:read` 并发布新应用版本；Netizen 不会用“未知发送者”降级提交。
+- 每条消息只表示一个 control 或一个 prompt；不能在一条消息里串联多个 slash control。
+- 未知的 `/command` 会明确拒绝，不会作为普通 prompt 交给模型。
+- 若要把以 `/` 开头的文字作为普通 prompt，使用 `//`。例如 `//plan this work` 会向 Codex 发送字面 `/plan this work`。
+
+### 回答 Codex 的问题
+
+普通会话、Goal 和 Side 中，Codex 发出结构化问题时，机器人会为每题发送一张“Codex 提问”卡片。
+选择一个建议，或选择“自行填写”并输入回答，再点击“提交回答”。选择建议时只提交该选项；
+只有选择“自行填写”时才提交文本框内容。
+自由填写最多 1,000 字符，较长回答可以直接在原会话发送。关闭进度卡不关闭问题卡片。
+
+- 问题卡片始终属于发出问题的原会话。普通会话如果后来切换了，提交时会提示先通过
+  `/sessions` 切回原会话；不会把答案发给新选中的会话。
+- Side 的问题只回答到原 Side；主会话切换、归档、删除或恢复不影响仍存活的 Side。
+  Side 关闭、过期或服务重启后，旧卡片不能恢复 Side，也不会把答案转给主会话。
+- 原会话仍在执行时，答案补充给当前任务；原会话空闲时，答案开始后续一轮。原提问任务
+  已结束本身不使卡片过期。准备回答期间若任务恰好结束、Goal 换轮或会话切换，会提示重试。
+- 机器人会另发一条回答回执，标明实际回答者。若会话开启“自动带上期间的群聊讨论”，
+  提交回答也沿用该模式，读取到这条新回执之前的讨论；这不使未 @ 的群消息自行触发任务。
+- 提交后查看聊天中的普通任务反馈。卡片校验失败时可修正后再次提交；进入普通输入处理
+  后，若提示需要重发，请在原会话直接发送回答。同一张卡片、同一用户和相同表单的重复
+  点击会被短期去重；修改回答会作为新的输入。若提示接收结果未确认，请先按提示检查或
+  恢复服务，不要重复提交。反馈失败不代表 Codex 没有收到回答。
+- 已归档、已删除、停止中、压缩中或不可用的会话沿用各自普通消息的限制。
+  原生审批和其他需要宿主处理的旧式提问不转成这类卡片。
+
+### 卡片、合并转发与转发话题
+
+- 可直接提供飞书 2.0 卡片、合并转发或转发话题，也可在单聊/群聊主线中回复它们并提问；群聊和
+  话题的触发仍需每条 @机器人。它们作为材料交给 Codex，材料里的 `/stop`、`/new`、
+  `$skill-name` 不会变成控制命令或激活 Skill，卡片按钮不会自动点击。
+- 飞书 1.0 卡片不支持；无论直接提供、引用、补充历史还是包含在转发中，都会明确拒绝，
+  不会只读取标题后继续执行。可复制所需文字后发送。
+- 直接提供材料时，Codex 会结合对话中已有的明确要求处理；没有明确要求时会询问用途。
+  转发话题只读取转发中提供的内容，不自动补读源话题的全部历史。
+- 合并转发和转发话题可以混合文本、2.0 卡片及附件。全包最多保留 50 个子消息节点和
+  16,000 字符文字，超出这两个限制会标明截断；最外层转发包内最多再嵌套三层，超过
+  深度限制则整条拒绝，不作截断提交。图片、文件、音视频和表情只提供
+  可见文字或附件描述，不读取像素、文件正文或音视频内容。
+- 卡片没有可提取的可见文字、转换混入隐藏交互内容，或转发中保留的子消息不支持、
+  无法读取时，整条请求会明确失败；可复制可见文字或拆分后重新发送。
+
+### 群聊的 @ 时读取的消息范围
+
+群聊主线和普通群话题的每个会话有两种消息范围，可在 `/new` 创建时选择，也可在会话
+空闲时通过 `/config` 切换：
+
+- “仅这条 @ 消息”（默认）：只把当前消息和用户显式选择的一条飞书引用交给 Codex。
+- “自动带上期间的群聊讨论”：仍然只有 `@机器人` 才触发，但触发时会有界读取同一群聊
+  主线或同一话题中，从该会话上一次已接受请求之后到当前消息之前的非机器人成员消息，
+  作为 Supplemental Context 一并提交。
+
+补充消息只是背景：其中即使写了 `/stop`、`/new` 或 `$skill-name` 也不会执行 control 或
+激活 Skill。普通消息以当前 @ 消息作为请求和回复锚点；问题卡片提交以新的回答回执为锚点。
+P2P、P2P 话题与 Side 固定使用“仅这条
+@ 消息”。切换会话、恢复会话或刚启用补充模式时，边界会重置到这次操作，因而不会补录
+该会话非 current 期间的讨论。
+
+使用聊天默认配置自动创建时，以触发创建的那条真实任务消息作为初始边界，同时执行
+这条任务；首轮不补读它之前的群聊讨论。后续从这个起点按相同的补充模式读取，当前消息、
+逐条引用和图片仍按原规则处理。
+
+每次实际带入至少一条补充消息时，Netizen 会在提交前公开回复带入条数；若扫描、条数、
+文本或不支持类型造成省略，也会在同一回执说明。最多保留最近 50 条补充消息和 64,000
+字符可见文本；图片与当前消息、引用消息共同使用每条 prompt 最多 20 张、单图 20 MB、
+总计 50 MB 的限制。被选中的消息或图片无法安全读取时，整条当前请求不会执行，修复后需
+重新 @ 发送。
+
+若提示“选中的补充上下文消息缺少可验证的消息、时间或真实发送者信息”，表示该条历史
+消息连消息 API 自带的发送者姓名都无法验证，属于罕见的数据缺失场景；这不是权限问题，
+无需开通任何权限，重新 @ 发送即可重试。Netizen 不会用“未知发送者”匿名提交历史消息。
+
+### 飞书逐条引用
+
+- 在单聊或群聊主线中使用飞书“回复”后提问，Netizen 会读取被回复的那一条消息，作为单层引用上下文。
+- 当前提问者与被引用消息发送者会分别标注，不会混成同一个人。
+- 可见文本可来自文本、富文本、2.0 卡片、日程、任务、投票和有界的合并转发等类型。
+- 引用不会递归追踪更早的回复链。话题中的回复首先属于该话题 Scope，不会再解释成逐条引用。
+- 被引用消息被撤回、无权限、超时、类型不支持或准备期间当前会话发生变化时，本条消息不会 start/steer；修复问题后应由用户重新发送。
+
+### 图片与其他附件
+
+- 当前消息、被引用消息和已选中的补充上下文消息中的普通图片、富文本图片可作为 Codex
+  原生视觉输入。
+- 每条 prompt 最多 20 张图片；单图最多 20 MB；原始字节合计最多 50 MB。支持 PNG、JPEG、GIF 和 WebP。
+- 图片按整条消息准入：任一图片不可读、格式不支持或超过限制，整条消息都不会 start/steer，不会只提交可用部分。
+- 直接发送文件、音视频，或在当前富文本中夹带不支持的附件时，整条请求会被拒绝，
+  不会丢弃附件后仅执行文字。卡片和转发材料按[材料输入](#卡片合并转发与转发话题)的范围读取。
+- 无论直接提供、引用还是补充历史，卡片和合并转发内部的图片、文件与音视频都不读取
+  二进制内容。独立的普通图片、富文本消息仍按上面的规则准备视觉输入。
+
+### 查看和发送本轮文件
+
+- 普通或 Side Turn 成功完成后，或 Goal 四项终态证据确认后其 exact 最终物理 Turn 成功完成时，
+  Codex 的结构化文件修改或图片生成记录若指向当前仍可访问的
+  普通文件，或包含本轮成功删除且已不存在的文件，最终回复下方会显示“本轮文件”。
+  Progress Card 关闭时，它和最终回复组成
+  现有完成卡；Progress Card 开启时，它进入最初的同一张运行卡并随终态折叠。
+  Project 不是额外的文件权限边界，只作为相对路径的解析基准，不会过滤 exact Turn
+  明确报告的其他目录文件。
+- 每页显示 8 个文件、总数和页码；列表不会用 Markdown 表格撑长，也不会静默截断。
+  单张卡片最多完整承载 400 个。多页卡片统一提供页码下拉框，选择后点击“跳转”即可直接
+  查看任意页，重启后也可继续使用；文件只有一页时没有翻页控件。
+  超过文件数或卡片编码容量时会明确提示，不发送残缺清单。
+- 图片和其他文件的按钮都显示“发送”。点击后，文件会作为真实飞书图片或文件消息回复该
+  卡片；平面卡片由此形成话题，原本就在话题中的卡片仍留在原话题。
+- 最终正文明确引用本地 PNG/JPEG/GIF/WebP 图片时，会直接显示图片，不要求是本轮生成的。
+  相对路径按会话工作目录解析；代码示例和普通文件链接不触发预览。图片不存在、不可读、
+  上传失败或超限时显示提示。正文引用不会增加“本轮文件”条目，原有条目和“发送”按钮不变。
+  没有正文引用的图片不自动上传。含预览的正文可能规范化 Markdown 的空白、列表或引用写法。
+  图片不会改变回复类型：原本的富文本仍是富文本，原本的卡片仍是卡片；卡片回退为富文本时保留已上传图片。
+  翻页和服务重启保留已上传的正文图片；后来修改图片时，正文预览与点击“发送”的内容可能不同。
+- 卡片的本轮文件区显示脱敏逻辑位置，不显示文件大小：Project 内是相对路径，原生生成图显示为
+  `生成图片/<文件名>`，账号 home 内的其他文件显示 `~/...`，不会显示云主机绝对路径。
+  不会自动上传全部文件，文件列表本身没有预览、diff 或“一键发送全部”。
+- 普通、Side 和 Goal 最后一轮成功执行都会按成功修改累计 `+N -M`，包括本轮新建子任务
+  的修改；同一行反复修改或改回原文仍累计，数字不表示最终净差异。例如修改一行再改回
+  原文计 `+2 -2`。本轮已删除的文件也保留条目和已知行数，标注“已删除”，没有发送按钮；
+  它们同样计入文件总数、分页与顶部总计。普通非图片文件行显示各自的数字。
+  binary、图片及证据不完整的文件不显示相应数字；子任务仍运行、读取失败或无法归属
+  本轮时，可能没有总计，但其他已知文件的数字仍保留。
+- 本轮文件不是快照。点击时会重新读取卡片记录的路径并发送当前内容；文件若已删除、变成
+  目录或卡片已失效，会明确失败且原卡片保持不变。同一路径后来被替换或重绑时，发送的是
+  点击时当前普通文件。
+- 普通/Side 完成或进度文件卡使用 v4 callback；Goal 与 Files 同卡时使用 v5，把有界的
+  Goal/Activity/Result 投影与完整文件清单保存在飞书 callback payload 中，因此翻页不会
+  丢失其他模块。Netizen 服务或 App Server 正常重启后，已发送卡片仍可翻页和发送，不会
+  为此保存本地 card session。正式推广前的测试卡不承诺跨版本兼容。
+- 文件来自本轮成功修改、生成图片及可用的原生 diff，并包括可确认归属的本轮新建
+  子任务；行数只累计成功修改，不与原生 diff 重复相加。Goal 只取最后一轮，Side 不聚合
+  更早的轮次。shell、MCP 或第三方工具的输出若没有进入这些原生记录，不会被扫描补齐；
+  最终答复里写出路径也不会自动把它变成卡片文件。
+
+## 会话与 Project 管理
+
+### 新建与配置 Project
+
+- `/new`：打开唯一的新建卡片。Project 下拉框展示全部 enabled Projects，不由 Netizen
+  截断或分页；Model 可继承 Codex，也可显式选择 Model、Effort 和 Speed。Reaction Pulse
+  默认关闭，Progress Card 默认开启，可独立选择；群聊和群话题还可选择 @ 时读取的消息范围。
+  同 Scope 当前或最近使用且仍 enabled 的 Project 可能被预选；没有历史偏好时需要明确
+  选择。提交后创建并切换 Lazy 会话；没有 enabled Project 时会引导先打开 `/settings`。
+- 任何带参数的 `/new ...` 快捷创建都已下线；请在卡片中选择。
+- `/settings`：打开实例设置卡片。当前可在 Projects 分区启用、停用、创建或登记 Project。
+- 停用 Project 只阻止用它创建新会话，已有会话仍可继续；Netizen 不会删除 Project 目录。
+
+### 默认会话配置与自动创建
+
+`/defaults` 打开当前聊天的一张配置表单，无需先创建会话。在话题中发送时，设置作用于
+所属群聊或单聊，供该聊天的主线与普通话题之后创建会话时使用；卡片会显示这一作用范围。
+
+- 已有当前聊天的精确配置：直接回填到表单，修改任意项后保存；也可以删除精确配置。
+- 没有精确配置但命中群名规则：回填继承的配置，并说明保存会为当前聊天建立精确配置，
+  不会改动群名规则。
+- 都没有：显示尚未配置，选择必填的 Project 后保存；其余选项沿用新建会话默认值。
+
+表单包括 Project、模型／思考强度／速度、三个任务反馈选项，以及群聊的消息读取范围。
+模型可以继承 Codex；单聊及其话题固定只读取当前消息。保存默认配置本身不创建会话，也不
+启动任务。`/new` 保持原有表单和预选行为，不从这里预填；`/config` 仍用于修改当前会话。
+
+Admin 可以逐条配置具体群聊或单聊，也可以按“群名包含关键词”设置有序规则。优先采用
+具体聊天的精确配置；没有精确配置时，按群名规则的顺序取第一条命中项。关键词不能为空，
+英文匹配不区分大小写，不支持正则、群聊／单聊类别兜底、精确配置批量设置或禁用覆盖项。
+群名规则适用于之后遇到的匹配群聊，无需预先为每个群配置。
+
+Admin 的“默认会话配置”页分为“指定聊天”和“群名匹配”两个 Tab，各自以列表展示，
+暂不提供过滤条件。“指定聊天”包含单聊与群聊配置；“群名匹配”按实际优先级排列，
+可通过上移、下移调整顺序。点击添加或编辑会打开右侧抽屉，保存后保留当前 Tab 和分页
+位置；删除当前页最后一条配置时会回退到上一页。
+
+删除精确配置后会重新匹配群名规则，所以删除并不等于关闭自动创建。默认值、规则顺序或
+群名的修改只影响之后的自动创建，不改变已有会话。归档或删除当前会话后，下一条任务仍可
+按默认配置创建新会话，不会自动恢复旧会话；状态暂时不可用的已有会话不会被替换。
+
+命中配置的 Project 已停用、删除，或模型设置失效时，会先说明“默认会话配置不可用”，
+再给出原有手动准备会话的提示，不尝试下一条规则。需要匹配群名但读取失败时，也会说明
+无法判断。Project 删除不自动清理默认配置，需通过 `/defaults` 或 Admin 修改、删除。
+会话已创建后的输入或任务失败继续按原有规则处理，保留会话，不自动重放失败消息。
+
+自动创建沿用现有的逐条 @、输入准备和并发规则；两条同时到达的消息不会各自自动创建
+一个会话，但不保证先触发创建的消息先执行，发生状态竞争时仍可能提示重发。群聊中的
+每条触发消息仍需 @，控制命令和 Side 不触发这项自动创建。
+
+### Admin Web
+
+实例还默认提供单管理员 Admin Web，用于跨飞书 Scope 集中筛选和管理 Projects、普通
+Sessions、Side Topics、会话默认配置与定时计划。它与飞书共用同一个 Registry/Runtime，但权限来自独立 Admin
+credential，不会因为某人是 Channel 参与者或 Binding 创建者而自动开放。实例管理员可从
+部署主机当前实例的 `<NETIZEN_ROOT>/credentials/admin-web-secret` 获取登录凭据；未指定
+安装位置时根目录为 `~/.netizen`。发送 `/admin` 可找回当前实例实际绑定的管理 URL 和
+根目录，无需先登记 Project 或创建会话，也不会调用模型。有效的 Side 话题同样支持；
+关闭或过期的 Side 仍返回原有结束提示。Admin 未启用时命令会明确说明。
+
+Admin 默认监听 `0.0.0.0`；首次未指定端口时从 `8787` 开始寻找可用端口，绑定后保存在
+本实例配置中，之后不自动换号。多实例的管理端口彼此独立；不要仅凭默认端口猜测入口。
+多网卡或服务器名称不明确时，部署者可在本实例 `config.yaml` 中设置 `adminWeb.accessHost`。
+仅提供 loopback 地址时需在服务器本机访问或自行建立隧道。`/admin` 不返回登录凭据、
+session token 或免登录链接，也不改变管理权限。该凭据不是飞书 App Secret，不应发送到
+聊天。Admin 使用受信内网 HTTP，不提供 TLS、OIDC、多管理员或 RBAC；不应直接暴露到
+不受信网络。普通使用者继续使用 `/settings`、`/defaults` 和当前 Scope 的会话命令。
+
+登录状态不会因闲置或使用时长自动过期。退出登录、服务重启或管理员轮换凭据后需重新
+登录；浏览器清除会话 Cookie 后也需重新登录。登录会话数量达到上限时，新登录会替换
+最早的会话（同一来源达到上限时优先替换该来源的会话）。
+
+登录页也不会仅因放置时间长而失效。它的一次性校验码提交后即失效，服务重启、凭据
+轮换或打开大量登录页后也可能失效；多个登录页还会共用 Cookie。遇到登录失败时，
+关闭其他登录页并重新访问 `/login`，不要后退重交旧表单。登录后的管理操作凭据仍有
+十分钟有效期，操作页面过期时需要刷新。
+
+Admin Web 可以管理 inactive/cross-Scope exact Binding，包括创建 Lazy、设为当前、修改
+Turn Settings、重命名、归档、恢复或恢复并设为当前、删除 Lazy、Stop 和 Release，也可
+在 Delete capability 可用时删除 active 或 archived 的原生 Thread。两类删除都需二次确认；
+materialized 删除的确认文案会显示会话、Scope、short ID，并说明原生 Thread、spawned
+descendants、Codex App/CLI 历史与本地 Binding 都会永久消失。它不能发送即时 Prompt、查看完整
+历史、启动/推进 Goal、Compact、删除 Side 墓碑或执行任意选择的批量 native mutation。Admin 可查看 @ 时读取的消息
+范围；但不能在没有 exact 飞书消息边界时新启用 catch-up，也不能把 catch-up 会话从后台
+直接设为 current。页面操作结果未知时应刷新对账，
+不要重放；服务重启或 credential 轮换会注销原 session。
+
+Sessions 页的 Project、Scope、会话状态和当前指针均支持多选；同一项取“或”，不同项
+取“且”。默认显示 Active、Lazy 和“状态未确认”；Project 可搜索并包含停用项目。
+“状态未确认”表示暂时无法确认原生会话的归档状态，不代表会话已经删除；可稍后刷新。
+目录读取失败时列表保留本地会话并提示状态不可用。“重置”恢复默认筛选、创建时间和
+每页数量。列表保留 ID 供排查。
+每页可选 10、20、50 或 100 条；列表区分会话的消息/话题位置、当前指针和运行状态，
+点击位置名称时，话题会话直接打开对应飞书话题的根消息；普通单聊和群聊主线打开所在聊天。
+“最近更新”显示原生会话的最近更新时间，按浏览器本地时区显示；它与标题、摘要一起随
+列表刷新更新。Lazy 显示“尚未开始”，时间暂时不可用时显示 `—`。
+Side Topics 页可按 Project、chat 与 route 状态
+筛选，并结束当前进程仍可控的临时 Side；它不提供删除墓碑。
+
+已确认归档且没有待核查运行活动的会话，运行态显示 `—`（已归档，不查询运行态），
+不再自动轮询；这不表示历史 Goal 不存在。归档中或结果未知的会话仍保留状态核查，
+恢复归档后重新读取运行态。其他会话通常每五秒刷新本地运行态，原生状态补读连续失败
+时逐步降低重试频率，最长每分钟一次；手动刷新可立即重新读取。切换到其他浏览器标签页
+或最小化窗口等使页面隐藏时暂停新轮询，已开始的请求仍可能完成；仅失去窗口焦点不一定暂停。
+通过其他客户端恢复归档后，需刷新 Sessions 列表才能反映新的会话状态。
+
+Projects 页的归档统计在状态不完整时显示“已确认”数量及另有多少会话待确认；读取失败
+时显示“未确认”，本地项目和会话总数仍可查看。
+Projects 页可“删除 Project 及关联 Sessions”。确认范围包含该项目的全部关联会话
+（含归档会话）、仍需关闭的 Side、定时计划和仍在创建会话的定时执行，不受 Sessions
+筛选影响；磁盘代码目录保留。提交后关联计划即删除，部分删除失败或同名 Project
+重新登记都不会恢复这些计划。
+全部成功后项目才从列表移除。部分失败、结果未知或 Side 尚在创建时，项目保持停用并
+展示剩余项；已成功删除的会话不会恢复。后续操作须刷新清单并重新确认，不会自动续删。
+
+#### Admin 系统维护
+
+“系统维护”显示当前 Python 安装与最近重启结果，只提供本实例“重启服务”，不再从
+管理页升级共享程序。程序升级由部署者在独立终端执行 `netizen update`，不能从将被
+停止的 Netizen 服务里执行。
+
+重启使用此实例已经绑定的 Python 环境中的当前程序，重新加载账号持久 shell profile，
+并执行启动数据检查与必要迁移；它不安装包、不切换 Python 环境，也不保证所有原生
+配置作用于已有 Thread。提交前确认停机影响：不等待任务空闲，会中断普通任务、
+暂停 Goal、结束临时 Side，之后不会自动续跑。重启失败不自动回滚用户配置或已迁移数据库。
+
+关闭页面、断线或等待超时不取消操作；响应丢失先刷新对账，不要重复点击。重启后需要
+重新登录查看同一操作的结果；页面连通不等于操作成功。“服务已恢复”只表示恢复证据
+得到确认，不改判原失败操作。结果未知时按提示检查实例状态与日志，不手改维护记录
+伪造成功。服务已经停止时管理页不可用，由部署者使用：
+
+```bash
+netizen status --root /absolute/path/to/.netizen
+netizen logs --root /absolute/path/to/.netizen
+netizen restart --root /absolute/path/to/.netizen
+```
+
+这些是宿主机 CLI 命令，不是飞书 slash 命令。`--root` 选择一个实例；未指定时采用
+NETIZEN_ROOT，再缺省为有效账号的 ~/.netizen。`netizen update` 更新调用它的 Python
+环境及其关联实例，拒绝 --root，不是仅更新当前聊天中的机器人。
+
+另一个 Python 环境 B 可以按 root 控制绑定 A 的实例，但 start/restart 仍运行 A，
+B 的 update 不涉及 A。切换环境必须先 remove 保留数据、解除绑定，再从 B start；
+不要加 --purge。remove 默认保留实例数据；--purge 才清理展示的有限实例文件，
+-y 只省去交互确认，不能绕过安全检查。实例移除不卸载共享程序，也不删除 Project、
+用户 Skills 或共享 Codex 历史；程序卸载交给原包管理器，先处理其关联实例。
+
+### 查找、切换和命名会话
+
+- `/sessions`：用分页卡片列出当前 Scope 的普通会话。当前会话置顶，其他会话可点击
+  “设为当前”；这只切换后续普通消息默认进入的会话，不会停止其他会话正在运行的任务。
+  所有 persisted materialized 历史行无论是 idle、running、stopping、Turn 观测不可用、
+  Goal 或 Compaction，都可“归档”或打开独立红色确认卡后“删除”；App Server 自己处理
+  当前原生活动。普通 Turn 行还可 exact“停止”，`turn-observation-unavailable` 行可
+  “重新检查”。空闲 Lazy 行仍可删除，但只删除本地 Binding。归档/删除非当前行不会改变
+  当前会话；操作当前行会清空当前会话指针。
+  会话优先显示原生名称，无名称时使用首条消息预览，并始终保留切换所需的短 ID。
+  暂时无法确认归档状态的会话仍保留在列表中，并标注“归档状态：未确认”；这不代表会话
+  已被删除。目录不可用时会明确提示，可稍后刷新。任务运行状态暂时读不到时显示“暂不可用”。
+  `/threads` 是兼容别名。
+- `/sessions archived`：列出当前 Scope 的已归档会话，可恢复并切换，也可通过独立红色
+  二阶段确认永久删除；删除直接使用与 active Thread 相同的 App Server primitive，不先恢复。
+  只列出已确认归档的会话；另有状态未确认的会话时会提示数量，目录不可用时明确报告查询失败。
+- `/resume <短 ID>`：切换到普通会话。已归档会话要先恢复。
+- `/rename [名称]`：重命名当前原生 Thread；省略名称时打开卡片。名称也会显示在 Codex App/CLI。
+  未命名会话会在新 Turn 启动后根据当前上下文后台生成名称，运行中补充消息不会重复触发。
+  已有名称保持不变，手动改名优先。自动生成失败不影响聊天，失败确认结束后下次新 Turn 会再尝试。
+  手动改名会等待已有名称写入完成后覆盖，无需因自动命名而重试；等待不阻塞聊天或其他会话操作。
+- `/release`：显式取消当前 active 普通会话在本 Netizen 连接上的订阅。它保留 Binding、
+  原生 Thread、历史、配置和 Task Feedback，下一条普通消息仍 resume 同一 native ID。
+  运行中、状态未知或有已登记后台 terminal 时会拒绝；Side 使用 `/side close`。
+
+短 ID 只用于当前 Scope 中的会话选择。不能拿另一个聊天或话题里的短 ID 跨 Scope 切换。
+
+### 归档、恢复和删除
+
+- `/archive`：确认后把当前 persisted 原生 Thread 直接交给 App Server 归档；Turn、Goal、
+  Compaction 或观测故障都不剥夺该控制。归档保留会话配置与 Task Feedback，并清空
+  当前会话指针；不会自动切换到另一会话。
+- `/unarchive <短 ID>`：恢复已归档会话并切换到它。
+- `/delete`：Lazy 会话二次确认后只永久删除本地 Binding；已有原生历史的 persisted 会话
+  会显示带 exact Thread identity 的更强红色确认，并直接委托 App Server 处理当前活动。确认后
+  永久删除原生 Thread、App Server 管理的 spawned descendants、Codex App/CLI 历史与
+  本地 Binding，无法恢复。
+- 删除失败不会自动再发一次 delete。系统会只读对账原生目录：明确仍存在时保留会话供用户
+  重新确认，明确已不存在时收尾删除 Binding，无法判定时只隔离该 Binding 的 lifecycle，
+  其他会话仍可使用。
+
+如果提示会话被其他 Codex 实例占用，本次操作未执行，其他会话和管理功能仍可使用。
+请在占用该会话的 Codex App 内归档，或在占用它的交互 CLI 内执行 `/archive`，然后回到
+原飞书聊天或话题，通过 `/sessions archived` 的“恢复并切换”或 `/unarchive <短 ID>`
+恢复原会话并重发消息。归档会结束目标会话及其子会话的运行活动；App 托管的 worktree
+还可能被清理。不要另开一个独立 CLI 执行归档来尝试抢占。若直接退出占用该会话的独立
+CLI，待其释放后也可以在飞书重发消息，无须归档。真正的请求结果未知仍可能要求重启服务，
+不能把这类错误当成明确的占用拒绝。
+
+`/rename`、`/archive` 命令和 `/delete` 只作用于当前会话，不支持在命令后附目标 ID。要
+重命名另一个普通会话，应先 `/resume`；`/sessions` 行内的“归档”和经独立红色确认卡的
+“删除”是明确例外，不需要先切换，也不改变 `/archive`、`/delete` 命令的语义。
+
+<a id="session-settings"></a>
+
+## Model、Effort、Speed、Task Feedback 与 @ 时读取的消息范围
+
+- `/new` 卡片可以为新会话选择继承 Codex 或显式 Model、Effort 和 Speed；群聊和群话题
+  还可选择 @ 时读取的消息范围；Reaction Pulse 默认关闭，Progress Card 和结束时 @ 提醒默认开启，可独立调整。
+- `/config` 原子修改当前会话后续新 Turn 的三项模型设置、三个 Task Feedback，以及群聊 @ 时
+  读取的消息范围。它不创建 Turn，也不能直接配置另一个会话；应先 `/resume`。
+- 当前 Turn 运行、停止中或正在压缩时不能修改配置。运行时的普通消息仍只会 steer 当前 Turn。
+- 已经开始的 Turn 沿用开始时捕获的 Task Feedback；之后修改只影响后续新 Turn。
+- 选项来自 Codex 实时模型目录，并在卡片提交及每次新 Turn 前重新校验；手册不维护静态模型名单。
+- `/new` 和 `/config` 卡片底部可展开“模型介绍与迁移提示”，按模型查看简介、支持的输入类型
+  及目录提供的迁移/退役提示。查看介绍不会修改选择或保存配置，也不会自动切换模型；
+  不是下拉选择后自动刷新的说明。
+- 若目录需要分页而当前 SDK 无法完整读取，会明确拒绝，不静默提供不完整的模型列表。
+- 没有 Netizen 会话配置时，三项显示“继承 Codex”，启动 Turn 时不显式传入三项覆盖；
+  这表示配置来源，不声称已经反查到 Codex 的实际有效值。保存显式选择后，每次新 Turn
+  都会重新解析并应用；当前 running Turn 仍沿用其启动配置。
+- 不提供 `/model`、`/effort` 或 `/fast` 独立命令。Fast 是同一模型的 Service Tier；Codex Spark 是独立 Model。
+
+## 状态、压缩与停止
+
+### `/status`
+
+`/status` 是只读快照，通常包含：
+
+- 当前会话短 ID、名称和首条消息预览；
+- Project、完整原生 Thread ID 和运行状态；Project 位于 Git work tree 时还显示 Git
+  决定的 branch header，Side 状态也使用同一信息；
+- 当前 Turn 的原生 checklist 与已接受 steer 次数；
+- 最近可观测完成 Turn 的上下文窗口用量；窗口大小可用时同时显示上限和已用百分比；
+- Model、Effort、Speed 以及它们来自 Netizen 会话配置还是继承 Codex；群聊会话还显示
+  @ 时读取的消息范围。
+- 本 Netizen 进程当前观察到的 Thread 订阅状态及自动释放倒计时。
+
+Checklist 可能尚未生成或因兼容门禁暂不可用；上下文用量也可能要等到可观测 Turn 完成后才更新。Git 行来自一次有界只读探测，非 Git 目录或探测失败时会省略，不影响其他状态。`/status` 不展示内部推理、完整工具日志或 ETA。
+
+当前固定 Codex 版本默认关闭生成 checklist 的 `update_plan` 工具。需要任务步骤时，可在
+Codex 原生配置中将 `tools.update_plan.enabled` 设为 `true`；Netizen 继承该配置，不会
+自动开启工具。工具开启后，checklist 仍需等原生任务实际生成，其他 Activity 展示不受此开关影响。
+
+Checklist 使用 `✓ completed`、`→ inProgress`、`○ pending`。成功 steer 后，旧计划会
+标记为可能尚未反映最近调整；收到下一次完整原生 plan 更新后整体替换并清除标记。
+后续普通 Turn 运行时，上下文用量保留并标为“上一轮完成时”，本轮可观测完成后再更新；
+用量未知时明确说明，不将其当成零。
+
+订阅状态是当前进程的瞬态投影，不是 Thread 或 writer 的生命周期证明。取消最后一个订阅
+后，App Server 还要求连续三十分钟没有订阅和活动才会卸载 Thread；`/release` 因此不会
+声称 writer 已立即释放。
+
+### `/compact`
+
+- 输入 `/compact` 压缩当前普通会话的上下文，不接受额外参数；会话须已有任务历史且处于空闲。
+- 若启动前读取会话历史超时或多次失败，会明确回复压缩未启动，并释放本次操作的占用。
+- 开始后状态显示为 `compacting`，完成前不能提交新任务、修改配置或再次压缩。完成后可以在同一会话继续提问。
+- `/stop` 不会中断压缩。压缩结果无法确认时，按回复中的提示处理，不要把开始回执当作完成。
+
+### `/stop`
+
+- `/stop` 中断当前 Scope 的 active Turn；没有运行任务时不会停止其他会话。
+- 若当前运行的是 Goal，会先持久化暂停 Goal，再中断其当前精确物理 Turn。
+- Netizen 随后请求清理 App Server 已登记的后台 terminal。
+- 重要限制：当前接口不保证前台工具进程退出。飞书显示“已中断”表示原生 Turn 终止，不是所有前台子进程都已退出的证明。
+
+## 定时任务
+
+定时任务自 v0.6.0 提供，支持私聊、普通群和话题群的执行投递。已安装实例是否提供此入口，
+以其 `/help` 和 Admin 页面为准。
+
+可直接在群聊或私聊中创建。比如在群里说：“每天北京时间九点，在当前群总结 test 项目的进展。”也可说
+“列出这个群的定时任务”“把周报改到周五下午五点”“暂停周报计划”“把周报任务现在跑一次”。省略目标 chat_id 和
+Project 时使用当前普通会话；在私聊中默认投递到当前私聊，也可明确给出 chat_id 和 Project。
+Netizen 不负责按会话名称搜索 ID，目标会话须能被机器人访问。自然语言管理工具由 Netizen 自动接入，不需要另外
+安装 MCP 或定时任务 Skill。
+
+执行目标有两种：每次在新话题执行，或在固定的原会话继续。比如“十分钟后在当前会话
+继续检查刚才的问题”，会沿用这条会话的上下文；到点时空闲就启动新一轮，运行中就把
+指令追加给当前任务。原会话目标创建后固定，后续切换会话不会把计划转投到新会话。
+切走后仍可通过 `/cron`、Admin 或自然语言管理计划，旧表单也保留原目标；只有执行时
+才要求目标会话当前激活，保存计划不会自动切回原会话。
+
+`/cron` 打开管理卡片，默认当前会话已启用且未结束的任务。通过筛选下拉框选择当前会话/全部计划及启停状态并确认，
+再选择任务，在原卡片查看详情、立即运行、编辑、启停、删除或展开最近执行；执行话题可通过飞书搜索定位。
+卡片每批提供最多 50 个任务选项，可翻页；筛选切换会清除旧选择，编辑和启停后保留仍符合筛选的任务。
+“刷新任务”只在选中任务后出现，用于重新读取该任务的信息；重新确认筛选可更新任务列表。
+新建入口在管理卡底部；有当前会话时另提供“在当前会话定时执行”。新建和编辑使用完整
+表单，填写名称、指令、频率及对应时间；新话题模式另选 Project 和会话配置，原会话模式
+沿用目标的当前配置。取消返回管理卡。时间字段旁标明适用频率，均按所填时区解释；
+校验失败保留填写内容，陈旧表单须刷新。私聊和群聊采用相同的创建流程。
+Admin 的“定时任务”页提供相同管理能力，也可点击“立即运行”。按 Project、启停状态和结束状态筛选，
+默认显示全部 Project 中未结束的计划，包含已暂停计划。新话题模式最后一次仍在启动、执行
+或结果待确认时也保留；原会话模式在输入交接结束后即可收尾，不等待业务任务完成。
+列表分别展示启停、是否结束和执行结果；已结束不表示执行成功。没有后续触发机会时不显示启停按钮，仍可编辑时间重新安排。
+点击目标会话名称可以打开飞书聊天。创建/编辑在独立侧边表单中完成：Project 从列表选择，
+一次性日期时间按表单中的时区填写，预览后保存；取消保留列表位置。新话题目标填写
+chat_id；原会话目标从会话列表选择，可按 Project、聊天/话题或会话短 ID 搜索，
+也可选择非当前会话，计划会自动暂停至该会话恢复为当前会话。
+
+“立即运行”按计划当前保存的指令和执行目标触发一次；原会话模式使用目标当时的配置。
+它不改变原定时安排、下次执行时间或启停状态；暂停、已结束的计划也可手动运行。
+重新启用只恢复未来自动触发，不等于立即运行。回执“已受理”表示触发成功，不表示任务
+完成；最近执行会标明“手动触发”或“定时触发”。新话题模式上次首轮仍在执行或状态
+不明时暂不能再次运行；原会话模式的下一次触发独立，但目标不可用或 Project 不可用时
+同样拒绝。Admin 响应未知时先查看最近记录；卡片原样重试和
+自然语言工具保留同一请求凭据核查，不会重复启动。
+
+新话题计划支持与 `/new` 相同的模型、思考强度、速度、执行中表情闪烁、过程卡、结束时 @ 提醒和消息读取范围。
+默认采用创建时当前会话的配置，可在“会话配置”中修改，也可自然语言指定，例如“使用当前
+配置，但开启过程卡”。保存后与来源会话独立；修改计划只影响后续执行，某次话题的 `/config`
+只修改那次会话。“自动带上期间的群聊讨论”只读取该次新话题内的增量，私聊不提供此选项。
+
+原会话计划不保存独立配置。每次先在原位置发一条“定时任务”触发消息，接收、表情、
+过程卡和异常反馈都沿用普通消息规则；开启 catch-up 时会补充上一条已接受边界到本次
+触发消息之前的群聊讨论。系统输入启动的新一轮不结束 @；若只是追加当前任务，原轮的
+过程卡、结果位置和结束 @ 均不变。记录“已启动新一轮”或“已追加当前任务”只表示输入
+已被接受，不表示工作完成。锚点发送失败或未知时本次不执行；输入接收未知不重试，
+也不额外阻塞下一次触发，但 Runtime 自身不可用时仍会像普通用户消息一样拒绝。
+
+支持一次性、每天、每周和每 N 分钟四种规则，精度为分钟。服务按整分钟检查到期计划，
+固定间隔计划可能等待接近一分钟才被触发；修改计划会主动唤醒检查。
+新计划默认使用服务主机解析到的 IANA 时区，保存后不随主机时区变化；无法解析时须填写，
+例如 `Asia/Shanghai`。
+每天/每周跟随该时区的当地时间；夏令时不存在的时刻跳过，重复时刻只执行第一次。
+固定间隔从创建后的 N 分钟开始，暂停后启用保留原时间基准。当前不支持任意 cron 表达式、
+每月或节假日日历。
+
+重复计划可设置截止日期时间，默认不限，例如：“每天九点提醒我，截止到九月三十日十八点”。
+`/cron` 和 Admin 的创建、编辑表单均提供可选截止时间，留空即可取消截止。
+截止时刻仍允许触发；截止不会停止正在执行的任务。新话题模式等待最后一次首轮收尾，
+原会话模式只等待最后一次输入交接收尾，随后计划显示已结束。
+
+新话题模式每次触发都新建独立飞书话题与普通持久会话，不带入创建计划时的聊天历史，也不切换
+来源私聊、群聊或话题的当前会话。应在计划指令中写清要做的工作和资源位置。结果在新话题
+交付；随后继续提问、`/status`、`/stop`、配置、归档和删除都沿用普通会话能力。
+
+- 暂停、修改或删除计划影响后续触发；已经认领的本次执行仍可能继续。删除计划保留
+  已有会话；在执行话题 `/stop` 只停止那次普通任务，不暂停计划。
+- 原会话模式在目标切走或归档时自动暂停，切回或恢复后重新具备执行条件；手动暂停的
+  计划仍保持暂停。暂停期间错过的时间不补跑，一次性任务过期就记为错过。删除目标会话
+  会同时删除关联计划。“立即运行”不会自动切换或恢复目标会话。
+- 新话题模式同一计划上一次首轮尚未结束时，定时触发跳过、手动触发拒绝；首轮结束后的人工交流不会阻止后续
+  定时触发。状态无法确认时先阻塞该计划，可查看最近执行并使用普通会话控制处理。
+- 停机期间错过的时间不补跑，执行失败不自动重试。正常运行迟到超过一分钟也记为
+  错过；错过的一次性计划须改成新的未来时间才能再次启用。
+- 停用 Project 时跳过新触发，已有会话可继续；删除 Project 会同时删除关联计划。
+
+定时计划与 `/goal` 的持续目标、`/status` 中的原生 plan/checklist 分开管理。
+Side 的 slash 命令白名单保持不变，不提供 `/cron`；在 Side 中用自然语言创建计划时须显式
+提供目标群和 Project，查询时可明确目标群或全部计划，因为临时 Side 没有普通会话的默认映射。
+
+## Side 临时话题
+
+Side 适合在不打断 Parent 会话的情况下讨论一个临时分支。
+
+- `/side [首轮问题]` 要求当前会话已经有原生历史。它从当前 Parent Thread 创建临时 fork，并在同一聊天中新建一个 sibling 话题。
+- 省略问题时只创建 Side；携带问题时，首轮问题和后续回复只出现在新话题。
+- 携带问题时，Codex 看到的首轮来源仍是原 `/side` 消息及其发送者；新话题中的问题副本
+  只承载 reaction 和最终回复。后续每条 Side Prompt 使用其实际发送者。
+- Parent 和多个 Side 可以并发，但共享同一个真实 Project 目录。
+- Side 在同一个临时 fork 上支持多轮：空闲时开始新 Turn，运行中继续 steer。
+- Side 创建时冻结 Parent 当时的 Model、Effort、Speed、Reaction Pulse、Progress Card 与结束时 @ 提醒；
+  Parent 后续 `/config` 不影响既有 Side。每轮 Side Turn 的表情、进度卡、富文本和文件卡
+  与普通 Turn 使用同一规则。
+- Side 内只支持普通 prompt、`//`、`/status`、`/stop`、`/admin`、`/help`、`/` 和 `/side close`。
+- Side 内不支持 Goal；需要 Goal 时回到普通会话。
+- `/stop` 只中断当前 Side Turn，Side 仍可继续；`/side close` 才真正结束 Side 并取消订阅。
+- Side 空闲两小时或 Netizen 服务重启后过期。旧 Side 话题不会自动变成普通会话。
+
+若 Side 显示创建或关闭结果不确定，应在原 Side 话题按提示重试 `/side close`，不要把它当普通话题使用。
+
+## Goal
+
+Goal 适合让 Codex 围绕一个持续目标自动推进多个物理 Turn。
+
+- `/goal`：查看当前会话的 Goal。
+- `/goal <目标>`：启动一个 Goal。
+- `/goal pause`、`/goal resume`、`/goal clear`：暂停、恢复或显式结束 Goal；同样的控制也
+  位于 Goal 卡中。
+- Goal 从启动、过程、暂停/恢复到终态只更新同一张组合卡。Progress Card 开启时增加过程
+  模块，关闭时仍保留 Goal 状态、结果和可用文件模块。过程中的任务清单是最近一次原生
+  上报，可能尚未反映追加消息；成功追加会单独给出接收回执，不展示累计追加次数。
+- 只有 Goal 真实完成、exact 最终物理 Turn 成功完成且四项终态证据全部确认时才会自动
+  结束并清理。paused、blocked、额度限制或收尾不确定都不会自动清理；卡片仍允许恢复或
+  显式结束。收尾结果不确定时不会自动重试，`/stop` 和 `/goal clear` 也不会绕过隔离，
+  但已确认的最终回答仍会显示。服务重启后的旧 Goal 控制按钮会过期；重新发送 `/goal`
+  会创建当前进程可安全校验的新控制卡。
+- Goal 运行期间，可以继续发送普通消息（也可引用消息、附图片或使用 `$skill`），
+  补充到当前物理 Turn；准备期间恰好换轮会明确提示重发，不会自动改投下一轮。
+  启动、暂停、收尾或状态未知时不接收；同一会话仍不能使用 `/compact` 或 `/config`。
+- 可以发送“暂停一下”让模型理解并处理；需要确定地发起暂停时使用 `/goal pause` 或 `/stop`。
+- `/stop` 会先暂停 Goal，再中断当前物理 Turn；它不会把 Goal 当普通一次性任务清除。
+- 当前不支持在 Goal objective 中调用 `$skill`；请先在普通消息中使用 Skill。
+
+Goal 和 Side 都依赖运行时原生能力门禁。如果当前 `/help` 没有显示相应命令，以当前实例能力为准。
+
+## Codex Skills
+
+- 可以直接用自然语言询问 Netizen 的使用方式；本 `netizen-user-guide` Skill 设计为在相关问题上自动匹配。
+- 要显式调用其他 Skill，可在普通消息开头写 `$skill-name ...`；同一消息开头可以连续引用多个 Skill。
+- Skill 会在 start/steer 前重新发现和校验。名称不存在、已禁用或路径失效时，本条消息不会执行。
+- 飞书不提供 `/skills` 浏览命令。想知道当前有哪些 Skill，可以直接用自然语言询问 Codex。
+- `$skill` 是普通 prompt 的一部分，不能和飞书 slash control 串成一个消息，也不能放进 Goal objective。
+- 本手册随该实例使用的 Python 安装包保存，Netizen 启动时只为自己的 Codex 进程加载内置
+  `netizen-user-guide` 与 `netizen-lark` Skills，不写入全局 `$CODEX_HOME/skills`。
+  可以显式发送 `$netizen-user-guide <问题>`。升级包后重启实例会加载对应版本；移除实例不删除共享安装的资源，
+  包卸载也不删除共享的用户 Skills。各实例仍复用服务账号的原生 Codex 登录和配置。
+
+## 与 Codex App/CLI 的差异
+
+Netizen 复用原生 Codex Thread、历史、配置和工具，但飞书不是 CLI/App 宿主界面。
+
+- 可在 CLI/App 中 resume 飞书创建的原生 Thread；CLI/App 新增的消息不会自动回填飞书。
+- Codex App 可直接打开本机工作区文件；飞书对支持的本轮文件改为在终态卡片中按需发送
+  到话题。飞书不会自动上传整个工作区或保存 Turn 完成时文件版本。
+- `/copy`、`/vim`、`/theme`、`/exit` 和 `/quit` 属于宿主界面或生命周期命令，在飞书中不可用。
+- `/plan` 和 `/apps` 当前没有安全、公开的高层 SDK 控制面，在飞书中不可用。
+- `$app` 当前不会被包装成原生结构化 attachment。
+- `/model`、`/effort`、`/fast` 被统一为 `/new` 和 `/config` 卡片。
+- 普通会话、Goal 和 Side 的结构化提问使用飞书选择/填写卡片，回答按各自普通消息消费；它不是原生
+  审批界面，也不要求原提问任务一直保持运行。详见[回答 Codex 的问题](#回答-codex-的问题)。
+- 已物化 Thread 必须已持久化且 Delete compatibility gate 可用；删除直接委托 App Server
+  处理当前原生活动。不想丢失历史时使用 `/archive`。
+- `/release` 只释放飞书服务当前连接的订阅，不删除 Thread；CLI/App 或其他 App Server
+  的订阅彼此独立。之后飞书仍可按原 native ID 继续。
+- Codex 认证、MCP、Skills、AGENTS、`config.toml`、sandbox 和其他原生配置来自服务用户的标准 Codex 状态，不由每个飞书 Scope 另建一套配置系统。
+- Netizen 定时计划独立于 Codex App 的自动化列表；自然语言管理只在 Netizen 的原生执行
+  连接中临时提供一个工具，不写用户 MCP 配置，也不改已有会话的指令继承。
+- Netizen 服务每次启动都会重新读取服务账号的 interactive login shell 导出环境；写入持久 profile 的 NVM PATH、代理和工具路径在重启服务后生效，不维护飞书专用环境文件。
+- 后台服务没有真实 TTY，也不会继承某个已打开终端中的临时 `export`、alias 或未导出的 shell function；这部分无法与宿主终端逐项镜像。
+- 新 Thread 的 approval mode 使用当前 Python SDK 的公开默认 `auto_review`；飞书不提供 Codex App 的 Ask/Custom 宿主选择器，也不能完整继承它们。
+
+## 常见问题
+
+### “我又发了一条消息，为什么没有新开任务？”
+
+如果普通 Turn 或 Goal 的当前物理 Turn 仍在运行，新消息会 steer 它；若恰好撞上完成或
+换轮，本条消息未执行并提示重发。启动、停止、收尾或压缩状态会拒绝普通消息。
+等待状态回到空闲、先 `/stop`，或 `/new`、
+`/resume` 到另一个会话，才能开始独立 Turn。
+
+### “群里机器人为什么没响应？”
+
+群主线和群话题的每条触发消息都必须重新 `@机器人`；未 @ 的消息不会触发响应。若当前
+会话选择“自动带上期间的群聊讨论”，这些消息可能在下一次 @ 时作为背景进入 Codex，但
+仍不会自己触发 Turn。还应确认机器人仍在群内，且飞书应用的可用范围和消息权限已发布。
+
+### “为什么不能修改配置？”
+
+当前会话可能正在运行、停止或压缩。等待其回到空闲后再用 `/config`；要配置别的会话，先 `/resume`。
+
+### “为什么没有执行中表情闪烁或进度卡？”
+
+新建会话的 Progress Card 默认开启，Reaction Pulse 默认关闭；已有会话保留原设置。
+可在 `/new` 卡片中选择，或等当前会话空闲后通过 `/config` 修改；两项互不依赖。
+即使 Reaction Pulse 关闭，任务
+accepted、成功 steer 和终态仍会尽力显示生命周期表情。Progress Card 关闭并不影响普通 Turn 的
+最终回复：没有文件时仍回复富文本/静态文本，有文件时仍使用完成卡。Goal 始终有一张状态
+与控制卡，关闭该选项只会隐藏 Activity 过程模块。Side 使用创建瞬间冻结的 Parent 选项；
+若想改变既有 Side 的反馈方式，需要回到 Parent 修改后重新创建 Side。
+
+### “为什么 `/delete` 删除不了？”
+
+已有原生历史的会话必须已持久化且当前实例的 Delete compatibility gate 可用。普通 Turn、
+Goal、Compaction 或 Turn 观测不可用时也会直接委托 App Server removal，不要求 Netizen 先确认
+终态。ephemeral、未持久化、compatibility gate 不可用或 App Server/存储故障仍会拒绝。失败提示
+若说原生目录仍存在，可重新发送 `/delete` 并再次确认；若说状态 unknown，目标会话会保持
+占用且不应连续点击，可由部署者正常重启后重新对账；其他会话仍可继续使用。只想隐藏并保留
+历史时使用 `/archive`。
+
+### “Turn 失败后还要换会话吗？”
+
+不用。`failed` 只结束本轮 Turn，原 Thread、历史和 Binding 都保留；回复会显示可用的错误
+原因和错误码。可修正问题、调整配置或稍后发送“继续”，在同一 Thread 开始新 Turn；
+不会自动重跑旧任务或撤销已执行的操作。如果显示 `turn-observation-unavailable`，说明仍无法
+确认 exact Turn，自动周期读取、Reaction Pulse 和进度卡轮询已停止，原消息上已记录的
+`Typing`/`THINKING` 也会尽力清理，但不会冒充任务已经结束；后续若确认终态仍会收到普通
+完成回复。新消息会先触发一次有界状态检查：确认上一轮结束后才开始新一轮；若上一轮仍
+运行，则将本条消息补充到原任务；仍无法确认时本条消息不会执行，并返回最近的具体原因。
+也可从 `/sessions` 重新检查，确认之前失败后会补发原因并解除本轮占用。
+检查期间若又停止或切换了会话，等待中的旧消息不会随后执行，需要重新发送。
+若先前停止尚未完成，恢复状态读取也不会撤销停止；请等待结束，或按提示重试 `/stop`。
+停止确认完成后，可以正常发送新消息开始下一轮。旧进度卡不会恢复更新，新一轮使用正常反馈。
+检查不是重新执行任务。停止、归档或删除仍可从 `/sessions` 操作；归档/删除不需要先修好观测，其他
+会话不受影响。
+
+### “`/stop` 已完成，为什么进程还在？”
+
+`/stop` 能确认原生 Turn 已中断，并请求清理已登记的后台 terminal，但不能证明前台工具进程已经退出。这是当前原生接口限制。
+
+### “CLI 能找到一个工具，为什么飞书里提示找不到？”
+
+先确认工具路径或变量已经写入服务账号的持久 shell profile，而不是只在当前终端临时
+`export`。Netizen 会在每次服务启动时重新读取 interactive login shell 的导出环境；修改
+profile 后需要由部署者执行 `netizen restart --root "<NETIZEN_ROOT>"`，指定目标实例。
+alias、未导出的 shell function 和依赖
+真实 TTY 的初始化不属于后台服务可继承的环境。Bash 用户若只在 `.bashrc` 配置 NVM，需
+确认 `.bash_profile` 或 `.profile` 会 source 它。
+
+### “Side 为什么不能继续了？”
+
+Side 可能因空闲两小时、服务重启或关闭流程进入终态而过期。旧 Side 话题不会恢复为普通会话；回到 Parent 后重新 `/side`。
+
+### “引用或图片失败后会不会只发送文字部分？”
+
+不会。引用或图片准备采用整条消息准入；任一必需资源失败时零 start/steer。修复权限、缩小图片或重新选择内容后，由用户重发。
+
+### “为什么任务生成了文件，却没有出现‘本轮文件’？”
+
+当前版本从成功修改、生成图片及可用的原生 diff 发现文件，并补充可确认归属的本轮
+新建子任务记录。Goal 只取最后一轮，Side 不读取 aggregate diff；两者都不聚合更早
+轮次。子任务读取有界，运行中或读取不到的文件不保证补齐。三者都不解析最终回复中的
+路径，也不扫描 Project。shell、MCP 或第三方工具生成但未进入这些原生记录的文件，
+以及压缩输出，都不会进入卡片。文件必须仍存在且是普通文件；
+Project 不是额外的文件权限边界，本轮明确报告的其他目录文件仍可出现。
+
+### “点击本轮文件后，拿到的是任务完成时的版本吗？”
+
+不保证。本轮文件不保存快照、摘要或修改检测；点击时发送卡片所记路径当前仍可访问的
+内容。若其他会话已经修改、替换或重绑文件，发送的是当前版本；若文件已消失或变成
+非普通文件，则拒绝发送并保留原卡片。