refine context flows and prompt guidance surfaces

Author: ChesterRa

.github/workflows/release.yml

@@ -7,7 +7,7 @@ on:
   workflow_dispatch:
 
 jobs:
-  build-and-publish:
+  verify-linux:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -38,10 +38,8 @@ jobs:
           python - <<'PY'
           import os
           import re
-          import sys
 
           def _read_pyproject_version(path: str = "pyproject.toml") -> str:
-            # Keep this check dependency-free and compatible with older Python versions.
             in_project = False
             with open(path, "r", encoding="utf-8") as f:
               for raw in f:
@@ -147,6 +145,113 @@ jobs:
           print("OK: bundled web UI + help playbook + MCP handshake")
           PY
 
+      - name: Upload verified dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dist
+          path: dist/*
+          if-no-files-found: error
+
+  verify-platform-smoke:
+    needs: verify-linux
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: windows-latest
+            label: Windows
+            run_windows_pty: true
+          - os: macos-latest
+            label: macOS
+            run_windows_pty: false
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install smoke deps
+        run: |
+          python -m pip install -U pip pytest
+
+      - name: Run Windows PTY smoke tests
+        if: matrix.run_windows_pty
+        run: |
+          python -m pip install -e .
+          python -m pytest -q tests/test_socket_special_ops.py tests/test_windows_pty_backend.py
+
+      - name: Download verified dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist
+
+      - name: Install verified wheel
+        run: |
+          python -m pip install --force-reinstall dist/*.whl
+
+      - name: Smoke test installed wheel on ${{ matrix.label }}
+        run: |
+          cccc version
+          python - <<'PY'
+          import json
+          import subprocess
+
+          proc = subprocess.Popen(
+              ["cccc", "mcp"],
+              stdin=subprocess.PIPE,
+              stdout=subprocess.PIPE,
+              stderr=subprocess.PIPE,
+              text=True,
+          )
+          assert proc.stdin is not None
+          assert proc.stdout is not None
+
+          proc.stdin.write(json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}) + "\n")
+          proc.stdin.flush()
+          init_resp = json.loads(proc.stdout.readline().strip())
+          assert init_resp.get("id") == 1
+          assert init_resp.get("result", {}).get("serverInfo", {}).get("name") == "cccc-mcp"
+
+          proc.stdin.write(json.dumps({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}) + "\n")
+          proc.stdin.flush()
+          tools_resp = json.loads(proc.stdout.readline().strip())
+          assert tools_resp.get("id") == 2
+          assert isinstance(tools_resp.get("result", {}).get("tools"), list)
+
+          proc.terminate()
+
+          print("OK: MCP handshake on installed wheel")
+          PY
+
+  publish:
+    needs:
+      - verify-linux
+      - verify-platform-smoke
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install publish deps
+        run: |
+          python -m pip install -U pip twine
+
+      - name: Download verified dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dist
+          path: dist
+
       - name: Determine repository
         id: repo
         run: |

.gitignore

@@ -41,6 +41,7 @@ uv.lock
 # Docs: VitePress build artifacts
 /docs/.vitepress/cache/
 /docs/.vitepress/dist/
+/docs/_archive_local/
 
 # Local iteration notes (not shipped)
 /docs/ITERATION_PLAN.md

README.ja.md

@@ -55,7 +55,7 @@ CCCC は `pip install` 一つで導入完了、外部依存ゼロ — データ
 | **唯一の事実源** | append-only ledger（`ledger.jsonl`）が全メッセージ・イベントを記録 — 再生可能、監査可能、喪失なし |
 | **信頼性のあるメッセージング** | 既読カーソル、attention ACK、reply-required 義務追跡 — 誰が何を読んだか明確 |
 | **統一コントロールプレーン** | Web UI、CLI、MCP ツール、IM ブリッジがすべて 1 つの daemon に接続 — 状態の分断なし |
-| **マルチランタイム編成** | Claude Code、Codex CLI、Gemini CLI、Copilot など 12 種のランタイムを同一グループ内で混在利用 |
+| **マルチランタイム編成** | Claude Code、Codex CLI、Gemini CLI など 8 種の主要ランタイムを混在利用でき、さらに `custom` ランタイムも扱える |
 | **ロールベース協調** | Foreman + Peer ロールモデル、権限境界と宛先ルーティング（`@all`、`@peers`、`@foreman`） |
 | **リモート運用** | Telegram、Slack、Discord、Feishu、DingTalk にブリッジ — スマートフォンからグループを管理 |
 
@@ -127,7 +127,7 @@ graph TB
         A1["Claude Code"]
         A2["Codex CLI"]
         A3["Gemini CLI"]
-        A4["+ 9 種"]
+        A4["+ 5 種 + custom"]
     end
 
     subgraph Daemon["CCCC Daemon · 単一ライター"]
@@ -169,7 +169,7 @@ graph TB
 
 ## サポートランタイム
 
-CCCC は 12 種のランタイムでエージェントを編成。同一グループ内で各 actor が異なるランタイムを使用可能。
+CCCC は 8 種の主要ランタイムでエージェントを編成し、残りは `custom` で扱えます。同一グループ内で各 actor が異なるランタイムを使用可能です。
 
 | ランタイム | MCP 自動設定 | コマンド |
 |-----------|:----------:|---------|
@@ -179,11 +179,8 @@ CCCC は 12 種のランタイムでエージェントを編成。同一グル
 | Droid | ✅ | `droid` |
 | Amp | ✅ | `amp` |
 | Auggie | ✅ | `auggie` |
+| Kimi CLI | ✅ | `kimi` |
 | Neovate | ✅ | `neovate` |
-| Copilot | — | `copilot` |
-| Cursor | — | `cursor-agent` |
-| Kilo Code | — | `kilocode` |
-| OpenCode | — | `opencode` |
 | Custom | — | 任意のコマンド |
 
 ```bash
@@ -203,7 +200,7 @@ CCCC は IM グレードのメッセージングセマンティクスを実装 
 - **Reply-required 義務** — 受信者が返信するまで追跡
 - **自動ウェイク** — メッセージ受信時、無効化された agent を自動起動
 
-PTY actor にはターミナル注入、headless actor にはシステム通知で配信。daemon が全メッセージの到達状態を追跡。
+メッセージは daemon が管理する配信パイプラインを通じて各 actor ランタイムへ届けられ、daemon が全メッセージの到達状態を追跡します。
 
 ## オートメーションとポリシー
 
@@ -306,19 +303,18 @@ cccc im start|stop|status
 
 ## MCP ツール
 
-エージェントは **49 の MCP ツール**（7 つの名前空間）を通じて CCCC と対話：
+エージェントは、コンパクトな action-oriented MCP surface を通じて CCCC と対話します。コアツールは常時公開され、追加サーフェスは必要時のみ capability pack 経由で有効化されます。
 
-| 名前空間 | 数 | 例 |
-|----------|:--:|------|
-| **セッション** | 2 | `cccc_bootstrap`（ワンコール初期化）、`cccc_help`（運用プレイブック） |
-| **メッセージング** | 7 | `cccc_message_send`、`cccc_message_reply`、`cccc_file_send`、`cccc_inbox_list`、`cccc_inbox_mark_read` … |
-| **グループ & Actor** | 10 | `cccc_group_info`、`cccc_group_list`、`cccc_actor_add/remove/start/stop/restart`、`cccc_runtime_list`、`cccc_group_set_state` |
-| **オートメーション** | 2 | `cccc_automation_state`、`cccc_automation_manage`（ルールの作成/更新/有効化/無効化/削除） |
-| **Context** | 19 | `cccc_context_get/sync`、`cccc_vision_update`、`cccc_sketch_update`、`cccc_milestone_*`、`cccc_task_*`、`cccc_note_*`、`cccc_reference_*`、`cccc_presence_*` |
-| **Headless** | 3 | `cccc_headless_status`、`cccc_headless_set_status`、`cccc_headless_ack_message` |
-| **システム** | 6 | `cccc_notify_send/ack`、`cccc_terminal_tail`、`cccc_project_info`、`cccc_debug_snapshot`、`cccc_debug_tail_logs` |
+| サーフェス | 例 |
+|------------|----|
+| **セッションとガイダンス** | `cccc_bootstrap`、`cccc_help`、`cccc_project_info` |
+| **メッセージングとファイル** | `cccc_inbox_list`、`cccc_inbox_mark_read`、`cccc_message_send`、`cccc_message_reply`、`cccc_file` |
+| **グループと actor 制御** | `cccc_group`、`cccc_actor` |
+| **協調と状態** | `cccc_context_get`、`cccc_coordination`、`cccc_task`、`cccc_agent_state`、`cccc_context_sync` |
+| **オートメーションと記憶** | `cccc_automation`、`cccc_memory`、`cccc_memory_admin` |
+| **必要時のみの拡張** | `cccc_capability_*`、`cccc_space`、`cccc_terminal`、`cccc_debug`、`cccc_im_bind` |
 
-MCP アクセスを持つエージェントは自己組織化が可能：受信箱の確認、返信、タスクとマイルストーンの管理、オートメーションルールの設定、ピアとの協調 — すべて権限範囲内で。
+MCP アクセスを持つエージェントは、権限境界の中で自己組織化できます。受信箱の確認、可視返信、タスク協調、自己状態更新、そして必要なときだけの追加能力有効化が可能です。
 
 ## CCCC の位置づけ
 

README.md

@@ -62,7 +62,7 @@ CCCC is a single `pip install` with zero external dependencies — no database,
 | **Single source of truth** | Append-only ledger (`ledger.jsonl`) records every message and event — replayable, auditable, never lost |
 | **Reliable messaging** | Read cursors, attention ACK, reply-required obligations — you know exactly who read what |
 | **Unified control plane** | Web UI, CLI, MCP tools, and IM bridges all talk to one daemon — no state fragmentation |
-| **Multi-runtime orchestration** | Claude Code, Codex CLI, Gemini CLI, Copilot, and 8 more runtimes in one group |
+| **Multi-runtime orchestration** | Claude Code, Codex CLI, Gemini CLI, and 5 more first-class runtimes, plus custom runtime support |
 | **Role-based coordination** | Foreman + peer model with permission boundaries and recipient routing (`@all`, `@peers`, `@foreman`) |
 | **Remote operations** | Bridge to Telegram, Slack, Discord, Feishu, or DingTalk — manage groups from your phone |
 
@@ -135,7 +135,7 @@ graph TB
         A1["Claude Code"]
         A2["Codex CLI"]
         A3["Gemini CLI"]
-        A4["+ 9 more"]
+        A4["+ 5 more + custom"]
     end
 
     subgraph Daemon["CCCC Daemon · single writer"]
@@ -177,7 +177,7 @@ graph TB
 
 ## Supported Runtimes
 
-CCCC orchestrates agents across 12 runtimes. Each actor in a group can use a different runtime.
+CCCC orchestrates agents across 8 first-class runtimes, with `custom` available for everything else. Each actor in a group can use a different runtime.
 
 | Runtime | Auto MCP Setup | Command |
 |---------|:--------------:|---------|
@@ -187,11 +187,8 @@ CCCC orchestrates agents across 12 runtimes. Each actor in a group can use a dif
 | Droid | ✅ | `droid` |
 | Amp | ✅ | `amp` |
 | Auggie | ✅ | `auggie` |
+| Kimi CLI | ✅ | `kimi` |
 | Neovate | ✅ | `neovate` |
-| Copilot | — | `copilot` |
-| Cursor | — | `cursor-agent` |
-| Kilo Code | — | `kilocode` |
-| OpenCode | — | `opencode` |
 | Custom | — | Any command |
 
 ```bash
@@ -211,7 +208,7 @@ CCCC implements IM-grade messaging semantics, not just "paste text into a termin
 - **Reply-required obligations** — tracked until the recipient responds
 - **Auto-wake** — disabled agents are automatically started when they receive a message
 
-Messages are delivered to PTY actors via terminal injection and to headless actors via system notifications. The daemon tracks delivery state for every message.
+Messages are delivered to actor runtimes through the daemon-managed delivery pipeline, and the daemon tracks delivery state for every message.
 
 ## Automation & Policies
 
@@ -314,19 +311,18 @@ cccc im start|stop|status
 
 ## MCP Tools
 
-Agents interact with CCCC through **49 MCP tools** across 7 namespaces:
+Agents interact with CCCC through a compact action-oriented MCP surface. Core tools are always present, and optional capability packs add more surfaces only when enabled.
 
-| Namespace | Tools | Examples |
-|-----------|:-----:|---------|
-| **Session** | 2 | `cccc_bootstrap` (one-call init), `cccc_help` (operational playbook) |
-| **Messaging** | 7 | `cccc_message_send`, `cccc_message_reply`, `cccc_file_send`, `cccc_inbox_list`, `cccc_inbox_mark_read` ... |
-| **Group & Actor** | 10 | `cccc_group_info`, `cccc_group_list`, `cccc_actor_add/remove/start/stop/restart`, `cccc_runtime_list`, `cccc_group_set_state` |
-| **Automation** | 2 | `cccc_automation_state`, `cccc_automation_manage` (create/update/enable/disable/delete rules) |
-| **Context** | 19 | `cccc_context_get/sync`, `cccc_vision_update`, `cccc_sketch_update`, `cccc_milestone_*`, `cccc_task_*`, `cccc_note_*`, `cccc_reference_*`, `cccc_presence_*` |
-| **Headless** | 3 | `cccc_headless_status`, `cccc_headless_set_status`, `cccc_headless_ack_message` |
-| **System** | 6 | `cccc_notify_send/ack`, `cccc_terminal_tail`, `cccc_project_info`, `cccc_debug_snapshot`, `cccc_debug_tail_logs` |
+| Surface | Examples |
+|---------|----------|
+| **Session & guidance** | `cccc_bootstrap`, `cccc_help`, `cccc_project_info` |
+| **Messaging & files** | `cccc_inbox_list`, `cccc_inbox_mark_read`, `cccc_message_send`, `cccc_message_reply`, `cccc_file` |
+| **Group & actor control** | `cccc_group`, `cccc_actor` |
+| **Coordination & state** | `cccc_context_get`, `cccc_coordination`, `cccc_task`, `cccc_agent_state`, `cccc_context_sync` |
+| **Automation & memory** | `cccc_automation`, `cccc_memory`, `cccc_memory_admin` |
+| **Capability-managed extras** | `cccc_capability_*`, `cccc_space`, `cccc_terminal`, `cccc_debug`, `cccc_im_bind` |
 
-Agents with MCP access can self-organize: read their inbox, reply, manage tasks and milestones, set automation rules, and coordinate with peers — all within permission boundaries.
+Agents with MCP access can self-organize: read inbox state, reply visibly, coordinate around tasks, refresh agent state, and enable extra capabilities when the current job actually needs them.
 
 ## Where CCCC Fits
 

README.zh-CN.md

@@ -62,7 +62,7 @@ CCCC 只需一条 `pip install`，零外部依赖 — 不需要数据库、不
 | **唯一事实源** | append-only ledger（`ledger.jsonl`）记录所有消息和事件 — 可回放、可审计、永不丢失 |
 | **可靠的消息语义** | 已读游标、attention ACK、reply-required 义务追踪 — 谁读了什么一清二楚 |
 | **统一控制面** | Web UI、CLI、MCP 工具、IM 桥接全部对接同一 daemon — 不存在状态分裂 |
-| **多运行时编排** | Claude Code、Codex CLI、Gemini CLI、Copilot 等 12 种运行时可在同一协作组内混用 |
+| **多运行时编排** | Claude Code、Codex CLI、Gemini CLI 等 8 种一线运行时可混用，此外还支持 `custom` 运行时 |
 | **角色化协调** | Foreman + Peer 角色模型，权限边界清晰，收件人路由精确（`@all`、`@peers`、`@foreman`） |
 | **远程运维** | 桥接至 Telegram、Slack、Discord、飞书、钉钉 — 手机上即可管理协作组 |
 
@@ -134,7 +134,7 @@ graph TB
         A1["Claude Code"]
         A2["Codex CLI"]
         A3["Gemini CLI"]
-        A4["+ 9 种"]
+        A4["+ 5 种 + custom"]
     end
 
     subgraph Daemon["CCCC Daemon · 单写者"]
@@ -176,7 +176,7 @@ graph TB
 
 ## 支持的运行时
 
-CCCC 跨 12 种运行时编排 agent。同一协作组内，每个 actor 可使用不同的运行时。
+CCCC 跨 8 种一线运行时编排 agent，除此之外还支持 `custom` 运行时兜底。同一协作组内，每个 actor 可使用不同的运行时。
 
 | 运行时 | 自动 MCP 配置 | 命令 |
 |---------|:----------:|------|
@@ -186,11 +186,8 @@ CCCC 跨 12 种运行时编排 agent。同一协作组内，每个 actor 可使
 | Droid | ✅ | `droid` |
 | Amp | ✅ | `amp` |
 | Auggie | ✅ | `auggie` |
+| Kimi CLI | ✅ | `kimi` |
 | Neovate | ✅ | `neovate` |
-| Copilot | — | `copilot` |
-| Cursor | — | `cursor-agent` |
-| Kilo Code | — | `kilocode` |
-| OpenCode | — | `opencode` |
 | Custom | — | 任意命令 |
 
 ```bash
@@ -210,7 +207,7 @@ CCCC 实现的是 IM 级消息语义，而不是"往终端里粘贴一段文字"
 - **Reply-required 义务** — 持续追踪直到收件人回复
 - **自动唤醒** — 收到消息时，已停用的 actor 自动启动
 
-PTY 模式的 actor 通过终端注入接收消息，headless 模式通过系统通知接收。daemon 对每条消息的触达状态持续追踪。
+消息会通过 daemon 管理的投递链路送达到各 actor 运行时，daemon 对每条消息的触达状态持续追踪。
 
 ## 自动化与策略
 
@@ -313,19 +310,18 @@ cccc im start|stop|status
 
 ## MCP 工具
 
-Agent 通过 **49 个 MCP 工具**（7 个命名空间）与 CCCC 交互：
+Agent 通过一套紧凑的 action-oriented MCP surface 与 CCCC 交互。核心工具始终存在，额外能力则通过 capability pack 按需暴露。
 
-| 命名空间 | 数量 | 示例 |
-|----------|:----:|------|
-| **会话** | 2 | `cccc_bootstrap`（一次性初始化）、`cccc_help`（操作手册） |
-| **消息** | 7 | `cccc_message_send`、`cccc_message_reply`、`cccc_file_send`、`cccc_inbox_list`、`cccc_inbox_mark_read` … |
-| **协作组 & Actor** | 10 | `cccc_group_info`、`cccc_group_list`、`cccc_actor_add/remove/start/stop/restart`、`cccc_runtime_list`、`cccc_group_set_state` |
-| **自动化** | 2 | `cccc_automation_state`、`cccc_automation_manage`（创建/更新/启用/停用/删除规则） |
-| **Context** | 19 | `cccc_context_get/sync`、`cccc_vision_update`、`cccc_sketch_update`、`cccc_milestone_*`、`cccc_task_*`、`cccc_note_*`、`cccc_reference_*`、`cccc_presence_*` |
-| **Headless** | 3 | `cccc_headless_status`、`cccc_headless_set_status`、`cccc_headless_ack_message` |
-| **系统** | 6 | `cccc_notify_send/ack`、`cccc_terminal_tail`、`cccc_project_info`、`cccc_debug_snapshot`、`cccc_debug_tail_logs` |
+| 能力面 | 示例 |
+|--------|------|
+| **会话与指引** | `cccc_bootstrap`、`cccc_help`、`cccc_project_info` |
+| **消息与文件** | `cccc_inbox_list`、`cccc_inbox_mark_read`、`cccc_message_send`、`cccc_message_reply`、`cccc_file` |
+| **协作组与 actor 控制** | `cccc_group`、`cccc_actor` |
+| **协调与状态** | `cccc_context_get`、`cccc_coordination`、`cccc_task`、`cccc_agent_state`、`cccc_context_sync` |
+| **自动化与记忆** | `cccc_automation`、`cccc_memory`、`cccc_memory_admin` |
+| **按需扩展能力** | `cccc_capability_*`、`cccc_space`、`cccc_terminal`、`cccc_debug`、`cccc_im_bind` |
 
-拥有 MCP 权限的 agent 可以自组织：读取收件箱、回复、管理任务与里程碑、设置自动化规则、与同伴协调 — 均在权限边界内。
+拥有 MCP 权限的 agent 可以在权限边界内自组织：读取收件箱、可见回复、围绕任务协调、刷新自身状态，并在当前工作真正需要时再启用额外能力。
 
 ## CCCC 的定位