fkst

质量强制 substrate — 让 LLM-driven 代码演化 能 自托管 / 自我修订 的 衬底。

权威设计源:docs/REQUIREMENTS.md 哲学 不动点:CLAUDE.md 设计 vision:docs/design.md 已知 design 缺陷:docs/backlog.md

系统依赖

• macOS (Linux 暂 未 测,launchd 移植 systemd 见 backlog 13)
• lua CLI
  • macOS:brew install lua
  • Linux:apt install lua5.5 或 yum install lua
  • 供 conformance/run_all.sh 在隔离 worktree 中跑 Lua 单测
• Rust toolchain(rustup install stable;cargo build --release 编译 supervisor + framework)
• codex CLI(@openai/codex via npm — npm install -g @openai/codex)— 部门 spawn_codex_sync 调用
• Git(默认 系统)

安装

发布包默认安装到 ${HOME}/.local:

curl -fsSL https://github.com/ChronoAIProject/fkst/releases/latest/download/install.sh | sh

需要其它前缀时追加 --prefix:

curl -fsSL https://github.com/ChronoAIProject/fkst/releases/latest/download/install.sh | sh -s -- --prefix /opt/fkst

需要安装指定版本时显式传 --version:

curl -fsSL https://github.com/ChronoAIProject/fkst/releases/latest/download/install.sh | sh -s -- --version "<tag>"

源码构建

git clone <fkst-repo>
cd fkst
cargo build --release --workspace

启动 supervisor

方法 A:launchd (macOS,推荐 — auto-restart on crash)

./scripts/install-supervisor-launchd.sh   # install plist + load via launchctl

launchd 含 KeepAlive: true — supervisor 死 自动 重启(per REQUIREMENTS §12.1)。 卸载:./scripts/install-supervisor-launchd.sh uninstall。

方法 B:nohup (临时 / debug)

RUNTIME_DIR="$(source scripts/fkst-config.sh; fkst_runtime_dir)"
mkdir -p "$RUNTIME_DIR"
nohup ./target/release/fkst-supervisor >> "$RUNTIME_DIR/supervisor.log" 2>&1 &
disown

状态查询

bash scripts/fkst-status.sh

显示:supervisor 进程 / handles / inbox 排队 / candidate worktrees / 演化树 / recent supervisor events / file locks。

演化通路 — 投 inbox

RUNTIME_INBOX="$(source scripts/fkst-config.sh; fkst_runtime_kind_path evolve_requests inbox/0000-my-spec.md)"
mkdir -p "$(dirname "$RUNTIME_INBOX")"
cat > "$RUNTIME_INBOX" <<EOF
# spec 标题

## 范围
... codex 该 改 啥

## 验证
... cargo build + test + run pass
EOF

file_watch raiser 自动触发 evolve 部门 → 三 solver approach 共识 → setup candidate worktree → spawn implement codex → 三 reviewer diff 共识 → verify → auto_promote 记录 approve / verify ledger。满足门后 auto_promote 自动发 promote_request 给 promoter。

推 promote 进 develop

git merge --no-ff dev-rc-<date>-<slug>_from_<parent> -m "..."
git push origin develop

promoter 部门消费 promote_request 时执行同一 chain-merge 模型:git merge --no-ff <chain-tip>。verdict / solver / review artifact 写入 runtime://pipeline/,由 runtime hidden ref 同步。

监督 — fkst-supervise skill

主 Claude 监督 fkst 自举 用 .claude/skills/fkst-supervise/ skill(per CLAUDE.md §自托管过渡期纪律)。skill 含 6 角度反思 + 元思考 递归 + 故障 判据 + 代码 通路 + Human:口吻 对话。

部门 lua 单测

bash conformance/run_all.sh

当前测试入口:simple lua CLI 调 departments/<dept>/main_test.lua。 需 brew install lua 装 lua CLI。

外部 host conformance

外部 host project 的规范起步验证入口是 fkst-framework conformance --project-root <path>。 本仓库编译后可直接用 release binary 跑:

./target/release/fkst-framework conformance --project-root <path>

该命令读取显式 --project-root,验证 host runtime / project layout、graph scan、 department non-empty 与 schema validation。它不从 cwd 推断 project root。

子项目 link

• docs/REQUIREMENTS.md — 完整 需求 + invariants + 已 接受 / 已 拒绝 方向
• CLAUDE.md — 哲学 不动点 + 操作 指令
• docs/backlog.md — 已 知 design 缺陷 + fix path
• docs/design.md — 当前 design vision + open questions
• docs/lua-library.md — 官方 fkst/ Lua library package root 与 require("fkst.<module>") 入口
• docs/release.md — 发布身份 只 来自 HEAD Git tag
• .claude/skills/fkst-supervise/SKILL.md — 监督 workflow + 反思 清单

⟦AI:FKST⟧