# Manage Title

在已启用 Agent Clarity 标题插件的范围内，每轮结束前维护“状态｜初始需求｜当前进展”。支持跨 Codex/Harbor...

- Repository: https://github.com/dongshuyan/compass-skills (764 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dongshuyan/compass-skills --skill manage-title -g -a claude-code -y`
Codex: `npx skills add dongshuyan/compass-skills --skill manage-title -g -a codex -y`
Cursor: `npx skills add dongshuyan/compass-skills --skill manage-title -g -a cursor -y`
Gemini CLI: `npx skills add dongshuyan/compass-skills --skill manage-title -g -a gemini-cli -y`

## Description

在已启用 Agent Clarity 标题插件的范围内，每轮结束前维护“状态｜初始需求｜当前进展”。支持跨 Codex/Harbor 账户的共享安装、账户全局或指定项目，简短问答也要核对。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 维护三段式会话标题

本 Skill 随 Codex 插件安装。参考并改编自 panda-z519/agent-session-titles 的 manage-session-title；许可见插件 LICENSES/agent-session-titles.txt。

本 Skill 依赖同一插件中的 `scripts/title_runtime.py`、Hooks 和安装记录。若它被单独复制到普通 Skill 目录、配套脚本缺失，保留标题，在本会话首次遇到时说明一次：需要从 `dongshuyan/compass-skills` 使用 `scripts/title_plugin.py` 安装完整插件。不要自行安装、创建状态或尝试其他改名方式。`metadata.internal` 用于让通用 skills CLI 默认跳过此内部 Skill，不影响 Codex 加载完整插件。

安装范围由脚本检查：共享包使用安装时固定的全局状态位置；普通包使用当前 `CODEX_HOME/agent-clarity/`。没有已启用的全局安装时，再检查当前 Git 根目录的项目安装。共享安装的启用记录和标题保护不会因切换 Codex/Harbor 账户而改变。没有启用记录时直接继续用户任务，不自行安装或启用。只管理调用者自己的会话，不能选择别的会话 ID。

全局模式覆盖各目录的新会话和继续对话的已有会话，也支持非 Git 目录及用户分叉；不批量处理未继续的历史会话，不处理内部子代理。项目模式继续只接管启用后新建的根会话。

明确初始需求后尽早更新；阶段或具体进展明显变化时再更新；每轮最终回复前按真实状态核对一次（标题仍准确也调用一次，脚本不会重复写入）。简短问答、没有其他工具调用的回合也要执行。不需要用户每次要求改名，不向用户汇报后台改名过程。

格式固定为 `状态｜初始需求｜当前进展`：

- 初始需求：用户最初希望解决的问题。首次确定后保持稳定，不随临时步骤改写。
- 当前进展：现在正在做的事，或已经完成的具体结果。不能只重复状态。比如 `验证手动改名保护` 比 `正在验证` 更有信息。
- 状态：讨论中、调研中、方案中、实现中、验证中、待确认、待验证、已完成、已暂停、受阻。回合结束不等于任务完成；只有满足任务要求才用“已完成”；尚待真实环境验证用“待验证”。

两个描述段各尽量控制在 6, 18 个中文字符，硬上限各 28 字符；不塞入路径、项目名前缀或枝节，不用分隔符或换行。格式示例：`验证中｜会话标题自动化｜检查手动改名保护`。

使用执行工具调用**本 Skill 所属插件**的 `scripts/title_runtime.py`。从本文件位置向上两级即插件根目录；使用其绝对路径，不能假设源仓库还在原位置。默认自动选择已启用的全局或项目范围：

```sh
python3 "/插件实际安装路径/scripts/title_runtime.py" set --topic "初始需求" --status "验证中" --progress "当前进展"
```

脚本读取当前 `CODEX_THREAD_ID`，通过 Codex API 检查调用目录、会话来源和启用范围，再实际改名并回读。首次接管已有三段式标题时保留中间的初始需求。需要显式选择时使用 `--global` 或 `--project "/当前 Git 根目录"`，放在 `set` 前。

用户手动改过哪一段，就保留那一段；其他段继续自动更新。无法可靠拆成三段的外部名称会整体保留，返回 `paused`。返回 `disabled`、`out_of_scope`、`pending` 或出错时保留标题并继续用户任务；不要反复重试、访问数据库或修改全局配置。