From 1e4596b4942ef15753ddf31581207b61e5c2b8f0 Mon Sep 17 00:00:00 2001 From: YSCJRH <118494497+YSCJRH@users.noreply.github.com> Date: Mon, 8 Jun 2026 18:35:45 +0800 Subject: [PATCH] docs: clarify Codex usage surfaces --- README.md | 6 ++++++ README.zh-CN.md | 6 ++++++ docs/codex-app-workday-guide.md | 10 ++++++++-- docs/codex-workday-plugin.md | 8 ++++++++ docs/mcp-client-setup.md | 6 ++++++ plugins/winchronicle-workday/.codex-plugin/plugin.json | 2 +- pyproject.toml | 2 +- src/winchronicle/_version.py | 2 +- .../winchronicle-workday/.codex-plugin/plugin.json | 2 +- tests/test_version_identity.py | 2 +- 10 files changed, 39 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 2087642..eae346e 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,12 @@ WinChronicle should not be read as a promise to match that product surface. ## Recommended Codex Usage +| Mode | Use it for | Boundary | +| --- | --- | --- | +| **Workday plugin** | Natural-language daily recording: `开始记录工作`, `查看工作记录状态`, `停止工作并总结`. | Record-only. Do not inspect, edit, test, commit, push, or release repository files. | +| **Read-only MCP** | Let an agent read local WinChronicle context through six fixed tools. | No MCP write tools, desktop control, screenshots, OCR, clipboard, audio, network, or arbitrary file reads. | +| **Development thread** | Ask Codex to modify WinChronicle itself. | Follow `AGENTS.md`; start from fixtures, schemas, tests, scorecards, and docs before behavior changes. | + When using Codex app or Codex CLI to develop WinChronicle: - Read `AGENTS.md` first and keep the local-first, UIA-first, harness-first, diff --git a/README.zh-CN.md b/README.zh-CN.md index e1abbcc..6f8450b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -66,6 +66,12 @@ AI 编程 Agent 如果能理解用户当前工作流，会更有用；但屏幕 ## Recommended Codex usage / 推荐的 Codex 使用方式 +| 模式 | 用来做什么 | 边界 | +| --- | --- | --- | +| **Workday 插件** | 用自然语言记录一天工作：`开始记录工作`、`查看工作记录状态`、`停止工作并总结`。 | 只记录工作。不要检查、编辑、测试、提交、推送或发布仓库文件。 | +| **只读 MCP** | 让 Agent 通过 6 个固定 tools 读取本地 WinChronicle 上下文。 | 没有 MCP 写工具、桌面控制、截图、OCR、剪贴板、音频、网络或任意文件读取。 | +| **开发线程** | 让 Codex 修改 WinChronicle 项目本身。 | 遵守 `AGENTS.md`；行为变更前先从 fixtures、schemas、tests、scorecards 和 docs 开始。 | + 使用 Codex app 或 Codex CLI 协助开发 WinChronicle 时： - 先阅读 `AGENTS.md`，保持 local-first、UIA-first、harness-first、read-only diff --git a/docs/codex-app-workday-guide.md b/docs/codex-app-workday-guide.md index 125d9c6..dddef1d 100644 --- a/docs/codex-app-workday-guide.md +++ b/docs/codex-app-workday-guide.md @@ -8,6 +8,12 @@ daily work recorder. It is separate from developing the WinChronicle repository. Use this guide only when the goal is daily work recording. It is not the MCP setup path and it is not a development-thread prompt. +| Codex surface | Use it for | Do not use it for | +| --- | --- | --- | +| Workday plugin | Start/check/stop/summarize a finite local work session. | Repository inspection, editing, tests, commits, pushes, releases. | +| Read-only MCP | Let an agent query existing WinChronicle context. | Writing files, clicking/typing, screenshots, OCR, clipboard, network calls. | +| Development thread | Maintain the WinChronicle repository. | Hidden recording or capture-surface expansion. | + Install WinChronicle and print the combined Codex readiness report: ```powershell @@ -143,6 +149,6 @@ WinChronicle does not add screenshot fallback, OCR fallback, clipboard capture, keylogging, desktop control, MCP write tools, cloud upload, audio recording, or LLM summarization to this flow. -The `winchronicle-workday` plugin calls the same read-only and workday CLI -commands. It improves the user entry point without expanding the capture +The `winchronicle-workday` plugin calls the same setup/readiness and workday +CLI commands. It improves the user entry point without expanding the capture surface. diff --git a/docs/codex-workday-plugin.md b/docs/codex-workday-plugin.md index 5a95a04..b2660b3 100644 --- a/docs/codex-workday-plugin.md +++ b/docs/codex-workday-plugin.md @@ -21,6 +21,14 @@ winchronicle workday intent "查看工作记录状态" --execute If you are using WinChronicle from a source checkout before editable install, use `python -m winchronicle` instead of `winchronicle`. +## Workday Plugin, MCP, Or Development Thread? + +| Surface | Purpose | Boundary | +| --- | --- | --- | +| Workday plugin | Natural-language daily recording in Codex App. | Record-only: do not inspect, edit, test, commit, push, or release repository files. | +| Read-only MCP | Tool-capable agents can query existing local WinChronicle context. | Fixed read-only tool list; no desktop control or write tools. | +| Development thread | Maintainers ask Codex to change WinChronicle code/docs. | Follow `AGENTS.md` and the harness-first workflow. | + The default stopped summary path is a Codex-assisted report grounded in local WinChronicle evidence. The plugin should use the CLI output as a local evidence package, then write a Chinese daily report that leads with what work appears to diff --git a/docs/mcp-client-setup.md b/docs/mcp-client-setup.md index 85435c6..f8cdbab 100644 --- a/docs/mcp-client-setup.md +++ b/docs/mcp-client-setup.md @@ -18,6 +18,12 @@ only want Codex App to start and stop daily work recording, use [Codex App Workday guide](codex-app-workday-guide.md). If you only want a safe fixture demo, use [Windows first run](windows-first-run.md). +| Surface | Use it for | Boundary | +| --- | --- | --- | +| Workday plugin | Natural-language start/status/stop/summarize actions. | Record-only; no repository inspection or development work. | +| Read-only MCP | Existing local context lookup through six fixed tools. | No write tools, desktop control, screenshots, OCR, clipboard, audio, network, or arbitrary file reads. | +| Development thread | Maintaining WinChronicle itself. | Not an MCP or recording surface; follow `AGENTS.md`. | + ## Generic Stdio Configuration Use this shape for MCP clients that accept a command and argument list: diff --git a/plugins/winchronicle-workday/.codex-plugin/plugin.json b/plugins/winchronicle-workday/.codex-plugin/plugin.json index ee8d777..b1f98ab 100644 --- a/plugins/winchronicle-workday/.codex-plugin/plugin.json +++ b/plugins/winchronicle-workday/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "winchronicle-workday", - "version": "0.2.27", + "version": "0.2.28", "description": "Thin Codex entry point for explicit WinChronicle workday recording.", "author": { "name": "YSCJRH", diff --git a/pyproject.toml b/pyproject.toml index 40a2d51..ff2229e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "winchronicle" -version = "0.2.27" +version = "0.2.28" description = "UIA-first local memory for Windows agents." readme = "README.md" requires-python = ">=3.11" diff --git a/src/winchronicle/_version.py b/src/winchronicle/_version.py index be2d7c2..968391a 100644 --- a/src/winchronicle/_version.py +++ b/src/winchronicle/_version.py @@ -1 +1 @@ -__version__ = "0.2.27" +__version__ = "0.2.28" diff --git a/src/winchronicle/codex_plugins/winchronicle-workday/.codex-plugin/plugin.json b/src/winchronicle/codex_plugins/winchronicle-workday/.codex-plugin/plugin.json index ee8d777..b1f98ab 100644 --- a/src/winchronicle/codex_plugins/winchronicle-workday/.codex-plugin/plugin.json +++ b/src/winchronicle/codex_plugins/winchronicle-workday/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "winchronicle-workday", - "version": "0.2.27", + "version": "0.2.28", "description": "Thin Codex entry point for explicit WinChronicle workday recording.", "author": { "name": "YSCJRH", diff --git a/tests/test_version_identity.py b/tests/test_version_identity.py index 8b562e8..196f2df 100644 --- a/tests/test_version_identity.py +++ b/tests/test_version_identity.py @@ -14,7 +14,7 @@ def test_project_runtime_and_mcp_versions_match(tmp_path): pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8")) project_version = pyproject["project"]["version"] - assert project_version == "0.2.27" + assert project_version == "0.2.28" assert winchronicle.__version__ == project_version assert _mcp_server_version(tmp_path / "state") == project_version