Skip to content

getting-started.md

Latest commit

 

History

History
322 lines (223 loc) · 7.58 KB

getting-started.md

File metadata and controls

322 lines (223 loc) · 7.58 KB

起步指南

适用环境：macOS + bash + Python 3.11+。

目标：把当前唯一保留的链路跑通：SessionStart 注入背景，Stop 归档 session 并按规则触发 reflection，reflection 写 memory / csep-reflect-* skill，csep recall 从 session 库召回历史上下文。

1. 安装

先确认本机有 Codex CLI 和 uv：

which uv
codex --version

普通用户不需要 clone 仓库。直接跑：

uvx csep setup

这条命令会安装 csep CLI、注册 Codex plugin marketplace，并打开 ~/.codex/config.toml 里的 plugin hooks 开关。

也可以用 curl 包装：

curl -fsSL https://raw.githubusercontent.com/T0UGH/codex-self-evolution-plugin/main/scripts/setup.sh | bash

本地开发者如果要从当前 checkout 安装，可以继续用：

scripts/install.sh

2. 初始化配置

csep setup 已经会启用插件。通常不需要手动初始化配置；没有配置文件时会使用默认值。

查看配置路径：

csep config path

写入默认配置：

csep config init
csep config validate

默认配置：

schema_version = 2

[session_reflection]
enabled = true
backend = "codex-app-server"
model = "gpt-5.3-codex-spark"
ephemeral = true
sandbox = "danger-full-access"
approval_policy = "never"
skill_prefix = "csep-reflect-"
timeout_seconds = 900
max_concurrent_jobs = 1

[session_reflection.trigger]
enabled = true
memory_stop_interval = 3
memory_context_chars = 16000
skill_tool_call_interval = 15
high_signal_immediate = true
skill_generation_mode = "one_shot_active"
active_job_stale_seconds = 1800

[session_recall]
enabled = true
stop_hook_archive = true

[log]
retention_days = 14

默认的 sandbox = "danger-full-access" 和 approval_policy = "never" 是为了让后台 reflection 能无阻塞完成写入和 receipt 落盘。它的信任边界不在 child 自述，而在父进程的 receipt validation：路径、hash、job identity、memory root 和 csep-reflect-* skill namespace 都会被校验。低信任或共享环境可以调低这两个值，但后台 reflection 可能因此需要人工确认或无法完成。

3. 检查 Codex Plugin Hooks

csep setup 会写入或更新 ~/.codex/config.toml：

[features]
plugins = true
hooks = true
plugin_hooks = true

[plugins."codex-self-evolution@codex-self-evolution"]
enabled = true

插件声明文件：

plugins/codex-self-evolution/.codex-plugin/plugin.json
plugins/codex-self-evolution/.codex-plugin/hooks.json

声明的生命周期入口：

SessionStart -> csep session-start --from-stdin
Stop         -> csep session-stop --from-stdin

如果当前 Codex CLI 还不支持 plugin_hooks，插件不会生效；先升级 Codex，再重跑 uvx csep setup。

4. 验证 SessionStart

手工写一条 memory 到当前 repo bucket：

REPO=$(pwd)
BUCKET=~/.codex-self-evolution/projects/$(python3 -c "import os; print(os.getcwd().replace('/', '-'))")
mkdir -p "$BUCKET/memory/refs"
cat > "$BUCKET/memory/MEMORY.md" <<'EOF'
# Project Memory

My favorite test passphrase is XANADU_RIVER_442.
EOF

新开一次 Codex 会话并提问：

codex exec --json 'What is my favorite test passphrase?' 2>/dev/null | grep -i XANADU

看到 passphrase 即表示 SessionStart 已把 stable background 注入当前会话。测试后清理：

rm "$BUCKET/memory/MEMORY.md"

5. 验证 Stop Hook 与 Reflection

正常跑一次 Codex：

codex exec 'Say one sentence in Chinese to test my Stop hook.'

Stop hook 会快速返回；如果触发规则认为需要 reflection，会在后台创建 job。等待 15 到 30 秒后查看：

csep session-reflect --status | python3 -m json.tool
csep status | python3 -m json.tool

关注：

字段 含义
session_reflection.latest.status 最新 job 状态
session_reflection.global_lock 全局 reflection 锁状态
session_reflection.trigger.latest_state 当前 session 的计数器与最近决策
session_recall.db_exists session recall 数据库是否存在

失败时先看：

~/.codex-self-evolution/session_reflection/latest.json
~/.codex-self-evolution/session_reflection/runs/<job_id>/receipt.json
~/.codex-self-evolution/session_reflection/runs/<job_id>/validation.json
/tmp/codex-self-evolution/session-reflect-*.log
~/.codex-self-evolution/logs/plugin.log

6. 手动调试 Reflection

保存一份 Stop payload 后，可以手动创建并执行 job：

csep session-reflect --hook-payload /path/to/stop-payload.json | python3 -m json.tool

只查看状态：

csep session-reflect --status | python3 -m json.tool

只要 validation.status 是 succeeded，说明 child thread 的写入声明和父进程边界校验都通过。

7. Session Recall

Stop hook 默认会把 transcript 归档到本机 SQLite/FTS：

~/.codex-self-evolution/session_recall/state.db

召回当前 repo 的历史片段时，把 csep recall 当作 rg over past sessions：搜短 needle，不搜长问题。

csep recall "trigger policy|review_memory|review_skills"
csep recall --recent

跨 repo 检索：

csep recall "session reflection|reflection job" --global

输出 JSON 便于调试：

csep recall "session reflection|reflection job" --format json | python3 -m json.tool

手动归档单个 transcript：

csep session-archive --transcript-path /path/to/session.jsonl --cwd /path/to/repo --session-id <id>

回填历史 Codex sessions：

csep recall bootstrap --root ~/.codex/sessions --since-days 14

同步历史 Claude Code sessions：

csep recall sync-claude --root ~/.claude/projects --since-days 14

8. 常见问题

plugin_hooks 不生效

先确认 Codex 支持插件 hook：

codex --help 2>&1 | grep -i plugin
codex plugin --help 2>&1 | head -20

再确认本地 plugin cache 已刷新：

scripts/install.sh
csep status | python3 -m json.tool

发布或排障前可以额外跑 runtime smoke。脚本使用临时 state dir，不会污染默认 recall DB：

scripts/smoke-runtime.sh

session_reflection.latest.status 是 skipped

这是正常状态之一。常见原因：

  • 当前 session 计数器还没达到 nudge interval
  • 只有归档价值，没有触发 reflection 的高信号
  • 同一个父 session 已有活跃 job，递归保护生效
  • [session_reflection] enabled = false

查看 session_reflection.trigger.latest_state.last_decision 可以知道具体原因。

session_reflection.latest.status 是 failed

优先查看：

csep session-reflect --status | python3 -m json.tool
tail -50 ~/.codex-self-evolution/logs/plugin.log

常见原因：

  • codex app-server proxy 当前不可用
  • child thread 没写 receipt.json
  • receipt 声明的写入路径越界
  • skill 前缀不是 csep-reflect-

csep recall 没结果

确认归档是否打开：

csep config show | python3 -m json.tool
csep status | python3 -m json.tool

如果是新安装，先跑几次真实 Codex 会话，或者手动回填：

csep recall bootstrap --root ~/.codex/sessions --limit-files 50

想重置本地状态

重置当前 repo bucket：

BUCKET=~/.codex-self-evolution/projects/$(python3 -c "import os; print(os.getcwd().replace('/', '-'))")
rm -rf "$BUCKET"

重置 session 级运行状态：

rm -rf ~/.codex-self-evolution/session_reflection
rm -rf ~/.codex-self-evolution/session_recall

不会删除 ~/.codex-self-evolution/config.toml 和 .env.provider。