Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 26 additions & 102 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,116 +1,40 @@
# ContextIME Agent Instructions

## Product identity
## 产品定义

ContextIME is a distributable, configurable Windows input method for software developers.
ContextIME 是一款面向软件开发者的 Windows 原生中文输入法。

It must eventually:
最终必须具备:

- install into the Windows input-method list;
- provide normal Chinese phonetic composition, candidates, selection, and commit;
- work across applications without requiring an editor extension;
- let each developer configure code, comment, string, terminal, chat, and project vocabulary behavior;
- use editor adapters only as optional high-precision context providers.
- 正常的拼音组合、候选、选词和上屏;
- 不依赖编辑器插件也能正常使用;
- 支持代码、注释、字符串、终端、项目词库等开发场景配置;
- 编辑器插件只作为可选的高精度上下文来源。

ContextIME is **not** primarily a VS Code extension, an input-mode switcher, or a wrapper that only controls another IME.
ContextIME 不是以 VS Code 插件、输入法切换器或控制其他输入法的外壳作为最终产品。

## Required source of truth
## 权威文档

Before planning or implementing non-trivial work, read:
进行非简单修改前,先阅读:

1. [`docs/product-intent.md`](docs/product-intent.md) — product identity and route decision;
2. [`docs/product-plan.md`](docs/product-plan.md) — product scope, milestones and acceptance;
3. [`docs/technical-route.md`](docs/technical-route.md) — architecture, upstream reuse, module boundaries and implementation order.
- `docs/product-intent.md`
- `docs/product-plan.md`
- `docs/technical-route.md`

If repository code, old roadmap entries or prototype behavior conflict with these documents, the product plan and technical route take priority until the user explicitly changes them.
如果旧代码、旧 Roadmap 或原型行为与这些文档冲突,以产品规划和技术路线为准,除非用户明确改变方向。

## Hard route constraints
## 当前最高优先级

1. The next product milestone must advance the installable Windows IME path.
2. Do not add editor-only features while the native IME baseline is missing, unless the task explicitly requests prototype maintenance.
3. Reuse mature IME foundations such as librime and an existing Windows TSF/Weasel implementation where technically and legally suitable.
4. Do not rebuild pinyin segmentation, dictionaries, candidate ranking, or candidate UI from zero without a written comparison proving reuse is unsuitable.
5. Do not call a VSIX, input-state controller, or keyboard-layout switcher the finished ContextIME product.
6. Do not claim TSF composition, RDP stability, installation, or application compatibility without executable evidence from the relevant environment.
7. Preserve working prototype code, but clearly label prototype components and prevent them from defining the product architecture.
8. M1 native input-method acceptance has priority over Chat, Search, Command Palette, Shader or other editor-specific refinements.

## Required planning output

Before a non-trivial change, state:

- the user-visible product outcome;
- whether the change advances the native IME, shared context engine, optional adapter, or prototype only;
- existing projects/libraries being reused;
- the shortest route to a verifiable result;
- acceptance tests and rollback boundary.

If the proposed work does not advance the requested outcome, stop and correct the route before coding.

## Architecture direction
当前只优先完成 Windows 原生输入法基线:

```text
ContextIME Windows IME
├─ reusable IME engine (prefer librime)
├─ Windows TSF/input-method frontend
├─ candidate and settings UI
├─ developer-context policy
├─ local user/project dictionaries
└─ optional adapters
├─ VS Code
├─ Visual Studio
└─ JetBrains
```

Current packages under `packages/` are prototype and reusable research assets:

- `policy-core`: candidate shared policy logic; retain only rules that make sense inside the real IME.
- `syntax-runtime`: reusable syntax-context engine.
- `vscode-adapter`: optional adapter/prototype, not the product entry point.
- `windows-runtime`: controller prototype; do not mistake keyboard-layout switching for a native IME frontend.

## First native milestone

The first acceptable native milestone is:

1. ContextIME installs and appears in the Windows input-method selector.
2. A user can activate it in a normal desktop text field.
3. Typing pinyin starts composition.
4. A candidate list appears.
5. Number keys or selection commit Chinese text.
6. English mode and Chinese mode both work.
7. Installation and removal are repeatable on a clean Windows test environment.

Until this milestone is demonstrated, prioritize native bootstrap, upstream reuse, packaging, and smoke tests over advanced context automation.

## Performance and privacy

- No LLM, cloud request, or repository scan in the per-keystroke hot path.
- Composition and candidate interaction must remain responsive under RDP.
- Project vocabulary extraction must be local, explicit, bounded, and must not upload source code.
- Store only the minimum data needed for user learning and configuration.
- Fail open: when context detection fails, preserve normal typing rather than blocking input.

## Verification

Run existing checks for affected prototype packages:

```bash
npm install --ignore-scripts
npm run check
```

Native IME work must additionally include Windows-specific build, registration, activation, composition, candidate, commit, uninstall, and clean-machine evidence. Unit tests alone are insufficient.

## Pull requests

PR descriptions must include:

- Product outcome
- Route classification: native IME / shared core / optional adapter / prototype maintenance
- Reused upstream and pinned version or commit
- Evidence produced
- Known unverified boundaries
- Next highest-leverage step

Do not merge a route-changing PR whose product outcome is ambiguous.
安装
→ 出现在 Windows 输入法列表
→ 可以激活
→ 输入拼音
→ 出现组合文本
→ 出现中文候选
→ 选择并上屏
→ 中英文模式正常
→ 与其他输入法并存
→ 可独立升级和卸载
Loading