From 1bbb1a0f673df0db556ea45dd571a58e1b59002e Mon Sep 17 00:00:00 2001 From: ZouR-Ma <2605315944@qq.com> Date: Wed, 14 Oct 2026 17:27:23 +0800 Subject: [PATCH 1/7] docs: add guidelines for platform and provider packages Document configuration migrations, host contracts, provider adapters, telemetry, and terminal rendering. Define dependency boundaries and module-specific validation commands. --- packages/config/AGENTS.md | 25 +++++++++++++++++++++++++ packages/contracts/AGENTS.md | 26 ++++++++++++++++++++++++++ packages/providers/AGENTS.md | 29 +++++++++++++++++++++++++++++ packages/telemetry/AGENTS.md | 27 +++++++++++++++++++++++++++ packages/tui/AGENTS.md | 28 ++++++++++++++++++++++++++++ 5 files changed, 135 insertions(+) create mode 100644 packages/config/AGENTS.md create mode 100644 packages/contracts/AGENTS.md create mode 100644 packages/providers/AGENTS.md create mode 100644 packages/telemetry/AGENTS.md create mode 100644 packages/tui/AGENTS.md diff --git a/packages/config/AGENTS.md b/packages/config/AGENTS.md new file mode 100644 index 00000000..241390b6 --- /dev/null +++ b/packages/config/AGENTS.md @@ -0,0 +1,25 @@ +# packages/config + +Inherits the [root rules](../../AGENTS.md). This package is `@step-harness/config`; its current implementation provides product-neutral startup configuration migrations. + +## Responsibilities and entry points + +- `src/index.ts`: public migration functions and option types. +- `src/migrations.ts`: migrate legacy credentials to `auth.json`, move sessions and managed binaries, migrate keybindings, and report deprecated extension directories. +- `test/migrations.test.ts`: migration and repeated-startup behavior in temporary directories. + +## Boundaries and invariants + +- Do not depend on other workspaces. Callers explicitly supply `agentDir`, `configDirName`, and the keybindings migrator; do not obtain them through a reverse dependency on coding-agent. +- Step identity, default directories, TOML reads and writes, model selection, themes, and resource resolution belong in coding-agent. Do not move those product policies here merely because this package is named config. +- Migrations operate only on the supplied global directory and corresponding project directory, never another product's default paths. +- Preserve existing-target handling, legacy-file markers, and credential-file permissions. Repeated execution must not overwrite already migrated user data. +- Inject product keybinding rules through `KeybindingsMigrator`; this package handles file reads and migration orchestration. +- Keep startup messages and interactive waits at existing call boundaries. The host decides whether protocol modes display messages or wait for input. +- Do not add silent deletion or broaden cleanup on migration failure. Distinguish skippable legacy formats from actual data loss that must be reported. + +## Validation and documentation + +- Run `pnpm exec vitest --run test/migrations.test.ts` here; run root `pnpm run check` after code changes. +- Migration changes cover first startup, repeated execution, existing targets, malformed inputs, and explicit non-default directories. Tests must not use real user configuration. +- Update the [package overview](README.md); update [configuration guidance](../../docs/step-configuration.md) when Step startup or storage behavior changes. diff --git a/packages/contracts/AGENTS.md b/packages/contracts/AGENTS.md new file mode 100644 index 00000000..b38592a2 --- /dev/null +++ b/packages/contracts/AGENTS.md @@ -0,0 +1,26 @@ +# packages/contracts + +Inherits the [root rules](../../AGENTS.md). This package is `@step-harness/contracts`; it provides independent host contracts and wire framing. + +## Responsibilities and entry points + +- `src/in-process/index.ts`: default package entry point. `agent-product.ts` and `session-handle.ts`: product capabilities, session driving, events, and approval types. +- `src/in-process/session-record.ts` and `host-event.ts`: record visibility and host events, modeled separately from real-time lifecycle events. +- `src/wire/index.ts`: `@step-harness/contracts/wire` entry point. `events.ts` and `protocol.ts`: wire events, handshake identity, version, and constants. +- `src/wire/frame.ts`: encoding and streaming decoding for uint32 big-endian length-prefixed frames and LF line frames. + +## Boundaries and invariants + +- Runtime dependencies remain empty. Do not introduce provider SDKs, agent-core, coding-agent, TUI, or concrete host objects. +- Keep contract types self-contained. Represent concrete messages and tool results as `unknown` at the boundary and validate them in consumers; do not bind to product internals through deep imports. +- Model product sessions, persistent records, and telemetry separately rather than combine them into an ambiguous event channel. +- This package defines contracts; do not assume every CLI RPC / stdio entry point already consumes them. Verify actual connections against current caller implementations. +- Wire framing handles serialized bytes or single-line text. It does not own JSON / CBOR serialization, process startup, network connections, or approval policies. +- Streaming decoders preserve incomplete trailing frames and return complete frames in order. Line framing rejects payloads containing LF; length framing counts bytes. +- Check both producers and consumers when changing protocols or event shapes. Do not change version constants without considering compatibility. + +## Validation and documentation + +- Run root `pnpm run check:contracts-deps-empty`; run the full `pnpm run check` after code changes. +- Run `pnpm exec vitest --run test/frame.test.ts` here. Framing changes cover split and combined chunks, empty payloads, and trailing-frame recovery. +- Update consumer SDK / mode documentation when connections change. Explain the relationship between independent contracts and existing RPC protocols explicitly. diff --git a/packages/providers/AGENTS.md b/packages/providers/AGENTS.md new file mode 100644 index 00000000..bd8d43c7 --- /dev/null +++ b/packages/providers/AGENTS.md @@ -0,0 +1,29 @@ +# packages/providers + +Inherits the [root rules](../../AGENTS.md). This package is `@step-harness/providers`; it owns model access, protocol adapters, catalogs, and credential resolution. + +## Responsibilities and entry points + +- `src/index.ts`, `models.ts`, `models-store.ts`, `types.ts`: public model interfaces, provider registration, catalog storage, and stream types. +- `src/provider/` and `src/dialect/`: separate provider-identity and API-dialect lookups. `src/api/`: protocol adapters such as OpenAI and Anthropic. +- `src/auth/`, `oauth.ts`, `env-api-keys.ts`: credential contracts, resolution, and OAuth. `src/step-provider/`: Step login protocols. +- `src/providers/all.ts`, `faux.ts`, `data/`, and `models.generated.ts`: built-in catalogs, the test provider, and generated snapshots. `src/metadata/`: presentation metadata. +- `scripts/generate-models.ts`, `model-data.ts`, `check-model-data.ts`: generation, structural validation, and offline-data integrity. + +## Boundaries and invariants + +- Internal dependencies are limited to telemetry. Do not depend on the Agent Loop, coding tools, product permissions, MCP, or CLI. Vendor SDKs and protocol differences stay here. +- Dispatch adapters by `model.api`. Provider identity, dialect `source`, and presentation metadata must not select a protocol implementation. +- Keep legacy identity derivation in `src/dialect/resolve.ts`. Register vendor compatibility quirks in `scripts/adapter-provider-quirks.json`; do not turn quirks into new dispatch mechanisms. +- Preserve explicit-credential overrides, stored credentials, and environment fallback precedence from `src/auth/resolve.ts`. Recheck and persist OAuth refreshes under the credential lock; failures must not silently fall back to environment credentials. +- Stream ordering, tool-call identifiers, cancellation, error settlement, and usage semantics must be consistent across adapters. Retries must not publish duplicate final events. +- The current public build's `builtinProviders()` returns an empty catalog. The product layer registers Step; configuration supplies custom models. Retained adapters do not mean all vendors are enabled by default. +- Do not hand-edit generated catalogs, snapshots, or manifests. Change generator scripts / inputs, then run root `pnpm run generate:models` and `pnpm run check:model-data`. Offline builds use committed data without silently refreshing remote catalogs. +- Pass credentials and telemetry contexts through explicit interfaces. Errors, fixtures, and diagnostics must not expose real tokens or keys. + +## Validation and documentation + +- Select regressions that do not access real services, such as `pnpm exec vitest --run test/dialect-provider-registry.test.ts test/faux-provider.test.ts`, from this directory. Protocol changes also run the relevant mock / conformance cases. +- Run root `pnpm run check:derived-compat-only`, `pnpm run check:no-provider-dispatch`, and `pnpm run check:metadata-not-in-dispatch`; run the full `pnpm run check` after code changes. +- Use root `./test.sh` for full validation with isolated resources and credentials; do not directly run tests that may activate real providers. +- Update the [package overview](README.md). Product configuration changes also update [models](../coding-agent/docs/models.md) or [custom providers](../coding-agent/docs/custom-provider.md). diff --git a/packages/telemetry/AGENTS.md b/packages/telemetry/AGENTS.md new file mode 100644 index 00000000..31102732 --- /dev/null +++ b/packages/telemetry/AGENTS.md @@ -0,0 +1,27 @@ +# packages/telemetry + +Inherits the [root rules](../../AGENTS.md). This package is `@step-harness/telemetry`; it provides backend-neutral telemetry contracts and reference implementations. + +## Responsibilities and entry points + +- `src/index.ts`: `TelemetryContext`, `TelemetrySpan`, serializable schemas, and type inference helpers. +- `src/noop.ts`: shared `NOOP_TELEMETRY_CONTEXT`. `src/memory.ts`: in-process reference implementation. +- `src/testing/`: the `@step-harness/telemetry/testing` entry point and `createTelemetryAdapterConformance` contract. +- `test/telemetry.test.ts`, `test/conformance.test.ts`: schema, reference implementation, and observable adapter behavior. + +## Boundaries and invariants + +- Do not depend on other workspaces or telemetry backends. Do not embed exporters, network delivery, global current-span state, or business state. +- Propagate contexts explicitly through parameters. Business packages define their own domain schemas; provider / session business rules do not belong here. +- `startSpan` invokes the business callback synchronously and exactly once, then waits for settlement. Preserve business return values and rejection reasons; convert synchronous throws to Promise rejections as specified by the existing contract. +- Recording methods are synchronous, passive, and non-throwing. Backend recording failures must not prevent business execution; ignore failed records atomically and ignore writes after settlement. +- Keep attribute merging, ignored `undefined` values, and last-write-wins status semantics consistent with conformance. Do not alter span lifecycles through premature settlement. +- No-op retains no names, attributes, or events. The in-memory implementation is a local / test reference with unbounded, process-local storage, not production persistence or a global cache. +- Schemas remain serializable, with type inference preserving name-to-attribute relationships. Update documentation and type tests when changing required fields, enumerations, or sensitivity / cardinality annotations. +- Private adapters, exporters, and endpoints stay in separate integration environments. Public contracts must not carry credentials or real sensitive business samples. + +## Validation and documentation + +- Run `pnpm exec vitest --run test/telemetry.test.ts test/conformance.test.ts` here; run root `pnpm run check` after code changes. +- Adapter-contract changes validate both no-op and in-memory references, including synchronous throws, asynchronous rejections, recording failures, and post-settlement writes. +- Update the [package overview](README.md). Consumers maintain domain-schema documentation, such as the [agent-core schema](../agent-core/docs/telemetry-schema.md). diff --git a/packages/tui/AGENTS.md b/packages/tui/AGENTS.md new file mode 100644 index 00000000..d2da439c --- /dev/null +++ b/packages/tui/AGENTS.md @@ -0,0 +1,28 @@ +# packages/tui + +Inherits the [root rules](../../AGENTS.md). This package is `@step-harness/pi-tui`; it provides terminal input, layout, and rendering primitives with zero AI dependencies. + +## Responsibilities and entry points + +- `src/index.ts`, `tui.ts`: public component, focus, overlay, and rendering interfaces. `tui-main-screen.ts`, `tui-alt-screen.ts`: regular / fullscreen differential output. +- `src/terminal.ts`, `stdin-buffer.ts`, `keys.ts`, `keybindings.ts`: terminal lifecycle, input sequences, and key recognition. +- `src/layout.ts`, `layout-node.ts`, `components/`: layout, containers, editors, lists, text, and image components. +- `src/utils.ts`, `terminal-image.ts`, `terminal-colors.ts`: visible column width, ANSI handling, image protocols, and color detection. +- `native/`: macOS / Windows input helpers and platform prebuilds. `test/virtual-terminal.ts`: controlled terminal tests. + +## Boundaries and invariants + +- Do not import Agent, provider, session, coding-product, or application-host code. Callers inject product themes, approvals, and message semantics; do not infer them from business objects. +- Measure width in visible terminal columns, not string length. Measurement, wrapping, truncation, and cursor positioning must handle CJK, combining characters, ANSI sequences, and image lines consistently. +- Preserve component `render(width)` and `invalidate()` contracts. Invalidate caches on content, width, or theme changes; dirty-start optimizations must not lose visual changes. +- Preserve distinct scrollback, viewport, selection, and differential-output semantics for regular and fullscreen modes. Do not conceal rendering defects with unconditional full-screen repaints. +- Use existing overlay, focus, and IME cursor interfaces. Restore focus after closing overlays; do not split input sequences / bracketed paste or misclassify them as individual keys. +- Settle resources for terminal start / stop, resize, color detection, and platform helpers. Do not add product refresh loops or dependencies on private local configuration. +- Native changes check platform source, build scripts, and corresponding prebuilds together. Do not replace only a local binary while breaking other platforms. + +## Validation and documentation + +- Run root `pnpm run check:tui-no-ai`; run the full `pnpm run check` after code changes. +- Use Node tests here, for example `node --test test/tui-render.test.ts test/tui-alt-screen.test.ts test/truncate-to-width.test.ts`, plus relevant input / overlay / cache regressions. +- Rendering changes cover narrow terminals, resize, CJK, ANSI, images, and both screen modes. Prefer the virtual terminal over real logins or model services. +- Update the [package overview](README.md), [editor styling](docs/editor-styling.md), or [product rendering pipeline](../../docs/tui-rendering-pipeline.md), as applicable. From a5d81cc4476e7e9e18aba1dfe128b3a2bf5d7876 Mon Sep 17 00:00:00 2001 From: ZouR-Ma <2605315944@qq.com> Date: Wed, 14 Oct 2026 17:27:23 +0800 Subject: [PATCH 2/7] docs: define agent runtime and coding product boundaries Describe Agent Loop, session, context projection, and compaction ownership. Keep coding-agent guidance at package scope and document tools, extensions, orchestration, and Step integrations against the current implementation. --- packages/agent-core/AGENTS.md | 25 +++++++ packages/agent-core/src/harness/AGENTS.md | 26 +++++++ packages/coding-agent/AGENTS.md | 90 +++++++++++++++++++++++ 3 files changed, 141 insertions(+) create mode 100644 packages/agent-core/AGENTS.md create mode 100644 packages/agent-core/src/harness/AGENTS.md create mode 100644 packages/coding-agent/AGENTS.md diff --git a/packages/agent-core/AGENTS.md b/packages/agent-core/AGENTS.md new file mode 100644 index 00000000..b8d697ed --- /dev/null +++ b/packages/agent-core/AGENTS.md @@ -0,0 +1,25 @@ +# packages/agent-core + +Inherits the [root rules](../../AGENTS.md). This package is `@step-harness/agent-core`; it owns the generic Agent runtime. + +## Responsibilities and entry points + +- `src/agent-loop.ts`: the single Agent Loop. `src/agent.ts`: state, steer / follow-up, and execution control. +- `src/types.ts`, `src/stream-fn.ts`, `src/proxy.ts`: runtime types and model-stream interfaces. +- `src/harness/`: context, sessions, compaction, resources, and generic tools; also read the [harness rules](src/harness/AGENTS.md). +- `src/node.ts`: Node entry point. `src/search/`: generic search capabilities. + +## Boundaries and invariants + +- Internal dependencies are limited to providers and telemetry. Do not depend on coding-agent, config, contracts, CLI, or TUI. +- Do not introduce vendor SDKs, Step defaults, CLI argument parsing, or UI objects. Products compose capabilities through stream, tool, environment, and resource interfaces. +- All product modes share this loop. New entry points must not copy the tool-call loop or message state machine. +- Preserve tool-call/result pairing, event ordering, cancellation propagation, steer / follow-up timing, and the distinction between errors and normal completion. +- Generic session context and persistence contracts belong in the harness. Product session adapters may compose them; client caches must not become authoritative state. +- Pass telemetry contexts explicitly. Disabling telemetry must not change business return values, errors, or execution order. + +## Validation and documentation + +- Select relevant cases from `test/` and run `pnpm exec vitest --run ` here. +- Run harness regressions with `pnpm exec vitest --run --config vitest.harness.config.ts `; fixtures must not access real model services. +- Update the [harness documentation](docs/harness.md) for generic runtime or session-contract changes. Product lifecycle changes also update the relevant root `docs/` guidance. diff --git a/packages/agent-core/src/harness/AGENTS.md b/packages/agent-core/src/harness/AGENTS.md new file mode 100644 index 00000000..2cbcccdb --- /dev/null +++ b/packages/agent-core/src/harness/AGENTS.md @@ -0,0 +1,26 @@ +# Generic harness + +Inherits the [agent-core rules](../../AGENTS.md). This directory implements generic context and session mechanisms. + +## Responsibilities and entry points + +- `agent-harness.ts`, `messages.ts`, `reducer.ts`, `system-prompt.ts`: execution composition, messages, and context semantics. +- `session/`: session state, context, in-memory implementations, JSONL codec / storage / repository, and storage conformance helpers. +- `compaction/`: cut points, summaries, branch summaries, lightweight request-time projection, and invariants. +- `tools/`, `types.ts`, `env/nodejs.ts`: generic tool primitives, explicit filesystem / shell contracts, and environment implementations. +- `skills.ts`, `skill-discovery.ts`, `prompt-templates.ts`: generic resource discovery and parsing. + +## Boundaries and invariants + +- Messages, session entries, and model-request context are distinct views. Projection changes only the pending request view; it must not rewrite transcripts, session trees, or compaction boundaries. +- Compaction retains current user intent, active tool-call/result pairs, and protected tails. Failure or cancellation must not persist partial summaries. +- Lightweight projection remains deterministic and disableable. Invalid projection falls back to original messages; do not lower estimates to conceal actual context pressure. +- Keep JSONL codec, storage, and repository layers independent. Recovery and branch reads follow existing entry / parent / leaf contracts. +- Tool I/O goes through explicit environment interfaces. Generic execution primitives do not own Step permission presets, approval UI, or product tool naming. +- `packages/coding-agent/src/core/compaction/projection.ts` reuses this package's projection implementation. Do not create a second algorithm; product adapters own product-specific summaries and skill retention. + +## Validation and documentation + +- From `packages/agent-core`, run `pnpm exec vitest --run --config vitest.harness.config.ts ` for affected session, compaction, or tool cases. +- Session implementation changes use the `session/testing` conformance contract. Context changes cover pairing, cancellation, failure, branching, and recovery. +- Update the [harness](../../docs/harness.md) and product [compaction guidance](../../../coding-agent/docs/compaction.md). diff --git a/packages/coding-agent/AGENTS.md b/packages/coding-agent/AGENTS.md new file mode 100644 index 00000000..acd48a57 --- /dev/null +++ b/packages/coding-agent/AGENTS.md @@ -0,0 +1,90 @@ +# packages/coding-agent + +Inherits the [root rules](../../AGENTS.md). This package is `@step-harness/coding-agent`; it composes the generic runtime into the coding product. Keep package guidance in this file, with subdirectory responsibilities and constraints described below. + +## Responsibilities and entry points + +- `src/index.ts`, `src/core/sdk.ts`, and `src/step/sdk.ts`: library and SDK capabilities. +- `apps/cli` composes process startup, argv handling, and mode routing; this package provides reusable product capabilities. + +## Directory responsibilities and contents + +| Directory | Responsibility | Contents | +| --- | --- | --- | +| `src/core/` | Coding-session execution mechanisms and product adapters for the generic harness | AgentSession, SessionManager, model and credential composition, resources and trust, message conversion, compaction, tools, and extension execution | +| `src/features/` | Concrete product features built on core and extension mechanisms | plan / task, subagents, workflows, goals, cron, questionnaires, stream recovery, feature registration, and switches | +| `src/step/` | Step product identity, policies, and external integrations | Defaults, login, TOML configuration, permissions, MCP / OAuth, plugins, SDK / stdio, feedback, and redaction | +| `src/modes/`, `src/server/` | Non-interactive modes and host service adapters | print, RPC, event output, and services that reuse the same product session | +| `src/theme/` | Product theme catalog and resolution | Built-in themes, active theme, theme loading, and color resolution | +| `src/render/`, `src/components/` | Product rendering helpers and reusable components | Rendering helpers and components; the full interactive host is in `apps/cli/src/ui/` | +| `src/cli/`, compatibility entry points, and `src/utils/` | Existing argument / command helpers, compatibility forwarding, and product utilities | Preserve existing call boundaries; new process entry points and mode routing belong in `apps/cli`, without extending frozen legacy entry points | +| `docs/`, `examples/` | Public interface documentation and usage examples | SDK, extensions, modes, sessions, tools, configuration, and extension examples | +| `test/` | Product and regression validation | Unit tests, session suite, faux-provider harness, and regression fixtures | + +### src/core: product runtime mechanisms + +| Area | Main locations | Responsibility | +| --- | --- | --- | +| Session execution | `agent-session.ts`, `agent-session-runtime.ts`, `agent-session-services.ts` | Compose the Agent Loop; manage product execution, events, queues, retries, and cancellation | +| Session storage | `session-manager.ts`, `session-manager-factory.ts`, `session-export.ts` | Persist coding sessions as JSONL, branch, resume, and export | +| Messages and context | `messages.ts`, `system-prompt.ts`, `compaction/` | Convert model messages, construct product prompts, summarize, retain skill instructions, and recover from context overflow | +| Models and credentials | `model-runtime.ts`, `model-registry.ts`, `provider-composer.ts`, `auth-storage.ts` | Compose model selection, credentials, and configuration into providers; reuse lower-layer protocol implementations | +| Settings and resources | `settings-manager.ts`, `resource-loader.ts`, `skills.ts`, `trust-manager.ts` | Read settings, discover resources, load skills, and enforce project trust gates | +| Coding tools | `tools/` | read / edit / write / bash / powershell / find / grep / ls, file mutation queues, and final tool-output retention | +| Extension execution | `extensions/types.ts`, `loader.ts`, `runner.ts`, `wrapper.ts` | Extension contracts, loading, command and tool registration, event hooks, and host capability injection | + +Core provides mechanisms that product features compose. Do not put a feature's state machine into tool loading, session storage, or the generic Agent Loop. + +### src/features: concrete features and orchestration + +| Feature | Main locations | Contents | +| --- | --- | --- | +| Feature composition | `index.ts`, `step.ts`, `step-capabilities.ts` | Built-in registration, capability selection, and switches | +| Plan / task | `step-plan.ts`, `plan-mode-tools.ts`, `step-tasks.ts` | Plan mode, plan-file write boundaries, structured tasks, recovery, and migration | +| Subagents | `step-subagent.ts`, `step-subagent-agents.ts`, `subagent/` | Agent definition discovery, persistent RPC children, lane lifecycles, notifications, results, and timeouts | +| Workflows | `workflow/` | QuickJS VM, host bridge, agent runner, journal, budgets, path ACLs, progress, and session-scoped Ultracode activation | +| Goal / cron | `step-schedule.ts`, `step-cron.ts` | Session-goal budgets and continuation; cron scheduling and durable jobs in trusted projects | +| Other product capabilities | `step-questionnaire.ts`, `step-stream-recovery.ts`, `llama/` | User questionnaires, stream recovery, and local model integration | + +Features connect through existing extension and session-event interfaces. Reuse core tools, sessions, and completion semantics rather than maintain another execution loop. + +### src/step: product policies and integrations + +- Configuration and identity: `defaults.ts`, `environment.ts`, `storage-root.ts`, `config-toml.ts`, `settings-manager.ts`; resolve Step directories, defaults, and `config.toml` consistently. +- Login and permissions: `auth.ts`, `login-flow.ts`, `login-status.ts`, `permissions.ts`, `command-policy.ts`, `shell-analysis.ts`; reuse provider login protocols while keeping policies and approvals in the product layer. +- MCP and plugins: `mcp*.ts`, `plugins.ts`, `path-containment.ts`; service discovery, catalogs, OAuth, contribution resolution, cancellation, and path boundaries. +- Product entry points and feedback: `tool-profile.ts`, `system-prompt.ts`, `sdk.ts`, `stdio-host.ts`, `feedback/`, `secret-redaction.ts`; capability composition, host adaptation, feedback consent, and redaction. + +## Boundaries and invariants + +- Internal dependencies are limited to agent-core, providers, config, and tui. Do not import CLI or turn app hooks into reverse dependencies. +- Reuse agent-core's Loop and generic harness. Implement coding-session message conversion, skill retention, permissions, and tool-output policies in this package. +- Provider protocols and vendor SDKs stay in providers. This package passes user configuration, credentials, model selection, and tool capabilities to providers. +- Preserve the frozen `bin` / `exports` boundary. Do not add argv, TTY, or process entry points, or weaken `check:coding-agent-entry-freeze`. +- Reuse `src/theme/` and `config.ts` for theme catalogs and resolution. Renderers consume the active theme; do not add another theme registry. +- Session completion, cancellation, recovery, and tool permissions remain consistent across RPC, print, TUI, and SDK. Protocol adaptation and presentation may vary by mode. +- Add features through existing extension / feature interfaces. Compatibility wrappers must not introduce independent core execution semantics. + +## Session, tool, and feature constraints + +- Distinguish `agent_end` from `agent_settled`, which includes retry / compaction recovery. Background delivery, goal continuation, and final completion use full settlement semantics. +- Propagate cancellation through model requests, retry waits, and automatic compaction. Late callbacks must not reactivate canceled runs or replaced sessions. +- Reuse agent-core for lightweight context projection; change only the request view, without persisting it or rewriting the transcript. Product summaries retain user instructions, skills, and protected tails; do not permanently delete session history. +- Tool permissions run through Step's `tool_call` policy; UI presents approvals. Handle dangerous matches and incomplete analysis separately: Ask / Approve for Me cannot bypass either gate through automatic tool overrides or unattended allow. Only risk-acknowledged Full Access uses the `skipCommandPolicy` exception; explicit tool deny still applies. Follow `src/step/permissions.ts` and [command permissions](../../docs/command-permissions.md). +- Use the existing mutation queue for changes to the same file. Final text results pass through the shared output-retention boundary, including MCP, extensions, hook replacements, and errors. Save full oversized output before publishing a preview; storage failure must not automatically retry calls with side effects. +- Preserve extension ordering: pre-execution `tool_call`, then return-stage `tool_result`. Publish catalogs in batches through `registerTools` to avoid repeated tool and prompt refreshes; tools added after a request starts become available to later requests. +- Keep persistent RPC sessions for subagents. Build child environments through `buildSubagentChildEnv`, retaining the child marker and workflow / cron / goal disabling flags. Timeouts, failures, and cancellation must settle lanes and release resources. +- Run user workflow code in the existing QuickJS VM through the restricted host bridge. Path ACLs and fan-out depth are separate contracts. +- Plan mode and structured task tracking are independent. Validate plan write paths; do not infer task state from reply numbering or completion markers. +- Persist goal controls before applying them. Clearing a goal revokes continuation and cancels its corresponding run. Deliver cron jobs when the host is idle with no pending user messages; preserve durable-store locking, atomic replacement, and rollback on failure. +- Configuration reads distinguish missing files, invalid TOML, and other I/O errors. Writes preserve fields such as `mcp_servers` from the read under the same lock; respect host-injected directories and project trust. +- Interactive MCP connects in the background; print / RPC wait for the initial catalog. Shutdown cancels connections and registration; late tools must not enter a new session. Isolate OAuth credentials by server identity and URL; do not borrow another product's identity. +- Preserve feedback consent, redaction, and endpoint injection. Public source must not embed private exporters, endpoints, or release configuration. + +## Validation and documentation + +- Run `pnpm exec vitest --run ` from this directory. For session regressions, prefer `test/suite/harness.ts` and faux providers; see the [test harness](test/suite/README.md). +- Run root `pnpm run check:coding-agent-entry-freeze`; run the full `pnpm run check` after code changes. +- Lifecycle changes cover cancellation, retries, compaction, queues, session replacement, and RPC. Permission tests use harmless shell fixtures; feature tests use fake RPC children, VM executors, and clocks. VM mocks do not replace actual isolation validation. +- Update public API documentation as applicable: [SDK](docs/sdk.md), [extensions](docs/extensions.md), [RPC](docs/rpc.md), [session format](docs/session-format.md), [output retention](docs/tool-output-retention.md), or [compaction recovery](docs/compaction-overflow-recovery.md). +- For product policies and orchestration, update [configuration](../../docs/step-configuration.md), [command permissions](../../docs/command-permissions.md), [orchestration lifecycle](../../docs/orchestration-lifecycle.md), [goal lifecycle](../../docs/goal-lifecycle.md), or [MCP catalogs](docs/mcp-catalog.md). From f5da5f9284c95a71acc61fab536687794da55900 Mon Sep 17 00:00:00 2001 From: ZouR-Ma <2605315944@qq.com> Date: Wed, 14 Oct 2026 17:27:23 +0800 Subject: [PATCH 3/7] docs: document CLI hosting and UI layer responsibilities Define startup, mode routing, process lifecycle, and protocol output boundaries. Document host-to-runtime-to-view dependencies, input handling, redraws, and focused validation. --- apps/cli/AGENTS.md | 27 +++++++++++++++++++++++++++ apps/cli/src/ui/AGENTS.md | 26 ++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 apps/cli/AGENTS.md create mode 100644 apps/cli/src/ui/AGENTS.md diff --git a/apps/cli/AGENTS.md b/apps/cli/AGENTS.md new file mode 100644 index 00000000..2822c49f --- /dev/null +++ b/apps/cli/AGENTS.md @@ -0,0 +1,27 @@ +# apps/cli + +Inherits the [root rules](../../AGENTS.md). This package is `@step-harness/cli`; it owns Step's process entry points and application host. + +## Responsibilities and entry points + +- `src/main.ts`, `src/index.ts`: top-level composition and public entry point. `src/bun/stepcode.ts`: standalone binary entry point. +- `src/args/`: argument definitions and mode selection. `src/commands/`: top-level commands. `src/bootstrap/`: environment, configuration, and extension composition. +- `src/modes/`: routing for interactive, print, JSON, RPC, and SDK stdio, reusing coding-agent execution capabilities. +- `src/ui/`: interactive terminal host, runtime, and view; also read the [UI rules](src/ui/AGENTS.md). +- `src/version.ts`, `assets/`: host version and terminal visual assets. + +## Boundaries and invariants + +- argv, TTY detection, process exit, signals, and stdout/stderr routing belong here. Agent Loop, session persistence, permission policies, and provider adapters belong in lower layers. +- Inject UI capabilities into coding-agent through hooks; `packages/**` must not import CLI. +- Non-UI code enters UI only through `#ui` / `#ui/index` or an equivalent public entry point, never deep UI internals. Use `#*` aliases only within this app. +- Keep JSON, RPC, and SDK stdio stdout limited to protocol output. Send diagnostics through the prescribed stderr / diagnostic channel; do not mix in startup banners. +- Keep startup waits specific to interactive, print, and RPC modes, especially background MCP connection in interactive mode versus waiting for the initial catalog in non-interactive modes. +- Use existing build identity and version resolution. Do not add independent version constants or infer product tags from package versions. + +## Validation and documentation + +- Run root `pnpm run check:layer-direction` and `pnpm run check:ui-layer`; run the full `pnpm run check` after code changes. +- Run `pnpm exec vitest --run test/package-command-paths.test.ts` here; select further regressions from `test/` for mode or startup changes. +- For manual TUI checks, run root `./step-test.sh --no-env` and explicitly supply isolated user-resource directories. The script removes listed environment credentials but does not isolate local login or configuration. Validate built artifacts with the actual built binary. +- Update [configuration](../../docs/step-configuration.md), the [rendering pipeline](../../docs/tui-rendering-pipeline.md), or coding-agent mode documentation as applicable. diff --git a/apps/cli/src/ui/AGENTS.md b/apps/cli/src/ui/AGENTS.md new file mode 100644 index 00000000..67773987 --- /dev/null +++ b/apps/cli/src/ui/AGENTS.md @@ -0,0 +1,26 @@ +# CLI interactive UI + +Inherits the [CLI rules](../../AGENTS.md). This directory presents session events and handles user input; it does not own Agent or persistent-session semantics. + +## Responsibilities and entry points + +- `index.ts`: the shell's single UI facade. `interactive-mode.ts`: interactive host and component composition. +- `startup-ui.ts` and selectors: startup login, trust, configuration, and session selection. +- `runtime/context.ts`: host injection interfaces. `runtime/session-events.ts`: events to views. `runtime/input-dispatch.ts`: input and actions. `runtime/redraw.ts`: redraw facade. +- `view/chrome/`, `view/dialogs/`, `view/editor/`, `view/transcript/`: presentation components. + +## Boundaries and invariants + +- Dependencies flow UI host → runtime → view. Runtime uses its own `RuntimeContext` and must not import the UI host or shell; view must not import runtime. The check script also reserves leaf-layer constraints for `ui/state/`; new state modules must not depend on higher UI layers. +- UI may cache rendering, queue presentation, selection, and input state. Read authoritative messages, tasks, goals, and session state from product sessions and events; do not reconstruct them from text. +- Use `@step-harness/pi-tui` for differential rendering, layout, focus, and input sequences. Do not copy the renderer or add an independent refresh loop. +- Request redraws through `runtime/redraw.ts`. Use the existing scheduler for streaming updates; force redraws only for established invalidation scenarios such as recovery, resizing, or theme changes. +- Use coding-agent's active theme and configurable keybindings. Measure, wrap, and truncate by visible terminal column width, covering CJK, ANSI, images, and narrow screens. +- Restore focus after closing dialogs. Async callbacks must not update closed or replaced sessions. Approval UI only presents and returns product-policy requests. +- The first frame and editor must not wait for slow MCP connections. While startup selectors own the screen, do not render the main UI first and cover it afterward. + +## Validation and documentation + +- Run root `pnpm run check:ui-layer`; run `pnpm exec vitest --run test/tui-acceptance-snapshot.test.ts` from `apps/cli`, then select relevant component tests. +- Validate layout or input changes in a controlled terminal, covering narrow screens, resize, paste, overlays, and regular / fullscreen modes. Explain visible behavior changes when updating snapshots. +- See the [rendering pipeline](../../../../docs/tui-rendering-pipeline.md) and [goal UI](../../../../docs/step-goal-ui.md). From 976a534e5f3fa60c1e04e3be6bfdf5826ff4afd0 Mon Sep 17 00:00:00 2001 From: ZouR-Ma <2605315944@qq.com> Date: Wed, 14 Oct 2026 17:27:23 +0800 Subject: [PATCH 4/7] docs: establish repository and support directory guidelines Connect module guidance through the repository architecture and ownership map. Add documentation, script, release, and plugin conventions while preserving the existing commit attribution policy and CLAUDE.md reference. --- AGENTS.md | 87 +++++++++++++++++++++++++++++++++++++++++ docs/AGENTS.md | 27 +++++++++++++ infra/release/AGENTS.md | 27 +++++++++++++ plugins/AGENTS.md | 28 +++++++++++++ scripts/AGENTS.md | 28 +++++++++++++ 5 files changed, 197 insertions(+) create mode 100644 docs/AGENTS.md create mode 100644 infra/release/AGENTS.md create mode 100644 plugins/AGENTS.md create mode 100644 scripts/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index cf6e7298..b96f24b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,3 +9,90 @@ - Before creating or amending a commit, inspect its metadata and remove any AI-client attribution trailer. This policy applies to commit metadata. Documentation may mention AI products when that is relevant to the product or feature being documented. + +## 1. Scope and reading order + +This file defines repository-wide rules for Step-Code. Before changing a directory, also read the `AGENTS.md` files in that directory and its ancestors. Local rules add module constraints; they cannot override this file's commit attribution policy, dependency direction, or public-source boundary. + +- `CLAUDE.md` continues to reference this file; do not maintain a second set of repository rules. +- Organize architecture guidance around layers, responsibilities, and ownership. Verify paths, dependencies, commands, and defaults against current source, `package.json`, check scripts, and the relevant documentation. +- Check implementation status before borrowing designs from other repositories. Do not copy obsolete paths, unimplemented plans, or private branch and release procedures. + +## 2. Layers and module entry points + +Dependencies flow from product entry points toward foundational capabilities. Foundational packages must not depend on products or applications. The table defines allowed internal dependencies, not a requirement to depend on every listed package. + +| Layer | Module and local rules | Responsibility | Allowed internal dependencies | +| --- | --- | --- | --- | +| Foundation | [telemetry](packages/telemetry/AGENTS.md) | Telemetry contracts, typed schemas, no-op and in-memory reference implementations | None | +| Foundation | [tui](packages/tui/AGENTS.md) | Terminal input, layout, differential rendering, and generic components | None | +| Foundation | [contracts](packages/contracts/AGENTS.md) | In-process host/Agent interfaces, wire events, and framing | None; runtime dependencies must remain empty | +| Foundation | [config](packages/config/AGENTS.md) | Product-neutral configuration migrations | None | +| Model runtime | [providers](packages/providers/AGENTS.md) | Providers, API dialects, model catalogs, credentials, and vendor adapters | telemetry | +| Agent runtime | [agent-core](packages/agent-core/AGENTS.md) | The single Agent Loop, generic harness, session and context semantics | providers, telemetry | +| Coding product | [coding-agent](packages/coding-agent/AGENTS.md) | Coding sessions, tool policies, extensions, orchestration, Step integrations, and themes | agent-core, providers, config, tui | +| Application host | [apps/cli](apps/cli/AGENTS.md) | argv, startup composition, mode routing, process lifecycle, and interactive UI | coding-agent, agent-core, providers, config, tui | + +- Register new workspaces in `pnpm-workspace.yaml`, root `package.json`, and `scripts/workspace-registry.json`. Use the `@step-harness/*` scope for new internal packages. +- Use public package entry points for cross-package calls. Do not depend on another package's `dist/` layout or bypass boundaries with deep source imports. +- `packages/**` must not import `apps/**`. `packages/tui` must not depend on Agent, provider, session, or product code. +- Put new vendor SDKs behind adapters in `packages/providers`. Coding-product integrations such as MCP and plugins belong in `packages/coding-agent`, not the generic Agent Loop or rendering library. + +## 3. Ownership of core concepts + +| Concept | Semantic owner | Product and host usage | +| --- | --- | --- | +| Agent Loop | `packages/agent-core/src/agent-loop.ts` | coding-agent composes it; TUI, print, JSON, RPC, and SDK reuse it. Do not create another loop. | +| Session / transcript | Generic session contracts in agent-core; coding-agent's `AgentSession` / `SessionManager` own coding-session execution and persistence | UI holds input, connection, selection, and presentation state; it must not become the authority for persistent sessions. | +| Context / compaction | Generic harness in agent-core; message conversion, skill retention, and recovery adapters in coding-agent | Presentation code must not assemble a second model context. Request projection must not rewrite the original transcript. | +| Provider / model | Registration, catalogs, dialects, and adapters in providers | Products select and configure models. Dispatch by API dialect, never by provider name or display metadata. | +| Tool / permission | Generic tool primitives in agent-core; coding tools, registration, permissions, and output retention in coding-agent | Clients present approval requests rather than duplicate permission decisions. Providers do not orchestrate tools. | +| Subagent / workflow / goal / cron / plan / task | `packages/coding-agent/src/features/` | Compose through extensions and the same session lifecycle. Do not infer state from UI text or model replies. | +| Configuration and resources | Neutral migrations in config; settings, trust, and resource resolution in coding-agent's core / step | CLI injects paths, defaults, and UI hooks. Step settings use `config.toml`; credentials, models, and sessions retain their own storage contracts. | +| Theme / TUI | Product themes in coding-agent's `src/theme/`; rendering primitives in tui; interactive composition in `apps/cli/src/ui/` | Components consume the active theme. Do not add another theme registry or rendering loop. | +| Host protocols | Independent in-process and wire contracts in contracts; concrete RPC / stdio protocols in existing mode entry points | Do not assume every mode already uses contracts. Adapt and validate new connections at host boundaries; keep concrete host objects out of contracts. | + +## 4. Choosing directories and implementing changes + +- Generic context, session, and tool primitives: `packages/agent-core/src/harness/`. Coding-product adapters: `packages/coding-agent/src/core/`. +- Built-in product features and orchestration: `packages/coding-agent/src/features/`. Extension loading, registration, and hooks: `packages/coding-agent/src/core/extensions/`. +- Step login, unified configuration, MCP, plugins, permissions, and feedback: `packages/coding-agent/src/step/`. Plugin manifests: `plugins/`. +- CLI commands and startup: `apps/cli/src/commands/`, `args/`, `bootstrap/`, and `modes/`. Product UI: `apps/cli/src/ui/`. +- Shell / bootstrap / modes enter UI only through `#ui` or `#ui/index`, never deep `#ui/...` imports. UI must not import the shell. +- UI dependencies flow host → runtime → view. Runtime receives host capabilities through its own `RuntimeContext`; view must not import runtime. If used, `ui/state/` is a leaf and must not depend on host, runtime, or view. +- Use existing actions and keybinding tables. Do not hardcode key matching in product logic. +- Provide complete TypeScript types for public interfaces. Prefer `unknown` with validation over unnecessary `any`; verify external APIs against installed dependency types. +- Relative TypeScript imports use `.ts` extensions and follow `check:ts-imports`. Source checked by the root configuration uses erasable syntax; do not add `enum`, parameter properties, or syntax requiring JavaScript emit. +- Do not hand-edit `packages/providers/src/models.generated.ts` or provider data snapshots. Change generator scripts or inputs, then run the corresponding generation commands. +- Preserve existing features and explicit user requirements. Do not delete functionality, weaken checks, or introduce unrelated refactors to make type or boundary checks pass. + +## 5. Development and validation + +- Use Node.js `>=22.19.0` and the pnpm version in the root manifest. Install with `pnpm install --ignore-scripts`; reproduce the locked environment with `pnpm install --frozen-lockfile --ignore-scripts`. +- Pin direct external dependencies to exact versions. Update the lockfile with dependency changes; do not update dependencies for documentation tasks or bypass lockfile commit checks. +- Run source through root `pnpm step` or `./step-test.sh`. `./step-test.sh --no-env` removes listed provider environment credentials, but local user resources still require care. +- After code changes, run root `pnpm run check`, inspect the full output, and fix errors. It includes Biome autofixes, type checks, and boundary checks; it does not run tests. +- Run relevant tests when changing tests. Run Vitest from the owning package with `pnpm exec vitest --run `; tui uses `node --test test/.test.ts`. +- Use `./test.sh` for repository tests and follow the pre-submission requirements in [CONTRIBUTING.md](CONTRIBUTING.md). It isolates user resources and credentials and builds offline if outputs are missing. Do not run a full Vitest suite that may activate real providers directly. +- Unit and regression tests use faux providers, fixtures, mocks, and temporary directories. They must not read real accounts or consume paid model requests. +- For documentation-only changes, verify relative links, directories, and commands and run `git diff --check`. Documentation changes alone do not require builds or model tests. +- When changing Agent Loop, sessions, tool permissions, providers, themes, or cross-process contracts, update the relevant `docs/`, package documentation, and affected `AGENTS.md` files. + +## 6. Task execution and Git collaboration + +- Before editing, read affected files, local rules, and relevant documentation. For complex or high-risk work, explain steps, tools, acceptance criteria, and rollback. Continue reversible work already authorized by the user. +- Prefer existing tools in `scripts/`. Keep temporary validation scripts in temporary directories, outside product source. +- Do not commit or push unless requested. Stage only explicit paths belonging to the task; do not use `git add .` or `git add -A`. +- If the working directory contains another task's changes, use a separate worktree or touch only your files. Do not stash, clean, or revert other contributors' changes. +- Do not use `git reset --hard`, `git checkout .`, `git clean -fd`, skip hooks, or force-push. If a Git operation conflicts with unrelated files, stop that operation and explain the conflict. +- Commits, PR/MR descriptions, issues, and comments must not include AI-client attribution, bot co-authors, or generated-by footers. Keep author / committer as the current human contributor's Git identity. +- Report the changes, validation evidence, and anything still unverified. Keep delivery notes concise and specific. + +## 7. Public source and support directories + +- Public source includes code, public tests, local builds, and CI checks. Private telemetry exporters, internal endpoints, release credentials, protected-tag operations, and upload/publication workflows stay in a separate release environment. +- Do not copy internal execution records, private CI configuration, or infrastructure addresses into this repository. Follow the [public-source boundary](docs/open-source-status.md) and `check:public-boundary`. +- Documentation: follow [docs/AGENTS.md](docs/AGENTS.md). +- Check and build scripts: follow [scripts/AGENTS.md](scripts/AGENTS.md). +- Local release packaging and installer templates: follow [infra/release/AGENTS.md](infra/release/AGENTS.md). +- Built-in plugin manifests: follow [plugins/AGENTS.md](plugins/AGENTS.md). diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 00000000..b2688d31 --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,27 @@ +# docs + +Inherits the [root rules](../AGENTS.md). This directory maintains repository-wide runtime contracts and topic guides. Package APIs and examples remain in their owning packages. + +## Responsibilities and entry points + +- `step-configuration.md`, `step-unified-config-and-mcp.md`: configuration, directories, trust, and MCP startup / write contracts. +- `command-permissions.md`: command analysis and product approvals. `orchestration-lifecycle.md`, `goal-lifecycle.md`: orchestration and goal lifecycles. +- `tui-rendering-pipeline.md`, `step-goal-ui.md`: CLI UI and terminal rendering integration. +- `open-source-status.md`, `THIRD_PARTY_PROVENANCE.md`: public-source boundaries and third-party provenance. +- Other topic / research documents must state their scope in the title and text; they do not automatically define current implementation rules. + +## Boundaries and invariants + +- Verify paths, exports, package names, defaults, configuration precedence, and commands against current source, manifests, and tests. Do not present old designs, research findings, or proposed work as implemented behavior. +- Root docs explain cross-module contracts. Packages own their SDK, extension, session, and tool guides; avoid duplicate defaults and API definitions. +- Distinguish configuration directories, user / project scopes, trust, missing / invalid / I/O errors, and writes under locks accurately. +- Lifecycle guidance explicitly covers cancellation, failure, retries, recovery, session replacement, and late background events. UI wording alone does not define runtime state. +- Permission guidance follows current presets and risk acknowledgments, including the Full Access exception. Do not describe incomplete analysis as safe or as a matched dangerous rule. +- Use relative links to repository files and resolvable example paths. Update references when source entry points move. +- Do not copy internal execution records, private CI / release procedures, endpoints, credentials, or unpublished implementations. Public examples use fake data and follow the [public boundary](open-source-status.md). + +## Validation and documentation + +- For documentation-only changes, check every added / modified link, source entry point, and command, then run `git diff --check`. +- Run root `pnpm run check:public-boundary` after staging new files so the tracked-tree check includes them. +- Use relevant module tests for examples involving executable code or protocols. Before submitting a PR, run repository checks required by [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/infra/release/AGENTS.md b/infra/release/AGENTS.md new file mode 100644 index 00000000..e31d13c4 --- /dev/null +++ b/infra/release/AGENTS.md @@ -0,0 +1,27 @@ +# infra/release + +Inherits the [root rules](../../AGENTS.md). This directory provides local release bundles and installer templates; see the [public-source boundary](../../docs/open-source-status.md). + +## Responsibilities and entry points + +- `release-bundle.mjs`: version normalization, local builds, versioned archives, SHA256SUMS, manifest / latest metadata, and installer-template rendering. +- `release-targets.json`: Darwin / Linux / Windows targets for arm64 / x64. +- `install.sh`, `install.ps1`: templates that resolve versions, download, verify, and install using an injected release base URL. +- Builds use root `scripts/build-binaries.sh`; tests live in root `scripts/release-bundle.test.mjs`. + +## Boundaries and invariants + +- This repository generates local artifacts only. Do not add uploads, protected tags, private CI, object-store SDKs, credentials, or internal publication services. +- When changing targets, check `release-targets.json`, the bundle's `TARGETS`, build scripts, and both installers together. Do not assume these files are generated from a single source. +- Use existing build identity for Step version / channel / commit, independently of compatibility-package versions. Keep version formats, archive names, manifest URLs, and checksums consistent. +- Preserve `tar.gz` for macOS / Linux and `zip` for Windows, with actual `step` / `step.exe` output names. +- Replace `__STEP_RELEASE_BASE_URL__` through template rendering. Tests use fake URLs; do not embed private addresses or credentials. +- Preserve platform detection, verification, failure cleanup, and PATH / installation-directory handling. Download or checksum failures must not report installation success. +- Packaging cleanup is limited to explicit artifact directories and the current temporary build directory. Installer updates follow existing target-directory handling without expanding into user configuration or unrelated files. + +## Validation and documentation + +- Run root `node --test scripts/release-bundle.test.mjs`. +- Check all six archive names with `node infra/release/release-bundle.mjs --version 0.1.0 --base-url https://release.example.test/stepcode --dry-run`, without starting actual publication. +- Run `bash -n infra/release/install.sh` for the shell template. Validate PowerShell changes on the corresponding platform and report any untested platforms. +- Update installation / local-build guidance; stage new files before running `pnpm run check:public-boundary`. diff --git a/plugins/AGENTS.md b/plugins/AGENTS.md new file mode 100644 index 00000000..b868ff3c --- /dev/null +++ b/plugins/AGENTS.md @@ -0,0 +1,28 @@ +# plugins + +Inherits the [root rules](../AGENTS.md). This directory contains public built-in plugin declarations; coding-agent owns runtime implementations. + +## Responsibilities and entry points + +- `playwright/step.plugin.json`, `steppage/step.plugin.json`: built-in plugin identity, MCP services, and provisioning declarations. +- `packages/coding-agent/src/step/plugins.ts`: manifest parsing, marketplaces, installation, contribution discovery, and the binary's embedded `BUILTIN_MARKETPLACE_FILES`. +- `packages/coding-agent/src/step/mcp.ts`, `mcp-environment.ts`, `path-containment.ts`: service connections, tool publication, effective environments, and resource path boundaries. +- Supported skill, agent, command, entry, and MCP declaration fields are defined by `StepPluginManifest` and its parsers. + +## Boundaries and invariants + +- Keep declarations and resources here, not a new Agent Loop, plugin loader, or permission policy. Also read the [coding-agent rules](../packages/coding-agent/AGENTS.md) when changing product integrations. +- Built-in plugin changes update both physical manifests and embedded copies / marketplace entries in `BUILTIN_MARKETPLACE_FILES`. Check source-launch and binary behavior. +- Use parser-supported fields for IDs, resource paths, commands, arguments, environments, and provisioning. Do not describe unsupported fields as effective configuration. +- Contribution paths use existing containment checks. Do not bypass plugin roots with absolute paths, `..`, or symlinks; project contributions follow the project trust gate. +- Resolve environment variables against the effective MCP launch environment. Declare required variable names without hardcoded tokens. An installed manifest does not mean its executable or valid credentials are ready. +- Built-in preinstallation preserves user uninstall markers and provisioning lifecycles. Manifest refreshes must not resurrect plugins the user uninstalled. +- Publish MCP catalogs through existing batch registration and session lifecycles. Canceled / shut-down sessions must not register late tools into new sessions; calls still pass through product permissions and output-retention boundaries. +- Public plugin declarations must not carry private endpoints, internal resources, user configuration, or real credentials. + +## Validation and documentation + +- From `packages/coding-agent`, run `pnpm exec vitest --run test/step-plugins.test.ts`; MCP integration changes also select corresponding mock regressions. +- Check JSON syntax, supported fields, and consistency between both forms of built-in declarations. Tests must not connect to real MCP services or automatically download / run installers. +- Run root `pnpm run check` after product-code changes. Stage new files before running `pnpm run check:public-boundary`. +- Update [MCP catalogs](../packages/coding-agent/docs/mcp-catalog.md) and [Step integration](../packages/coding-agent/docs/step-integration.md). diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 00000000..463e5263 --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,28 @@ +# scripts + +Inherits the [root rules](../AGENTS.md). This directory owns repository checks, builds, generation, and local development helpers. + +## Responsibilities and entry points + +- `check-*.mjs`: dependency, layer, entry-freeze, protocol-dispatch, public-boundary, credential, and commit checks; use root `package.json` to verify how they are invoked. +- `workspace-registry.json`, `adapter-provider-quirks.json`, `__baseline__/`: workspace registration, adapter compatibility exceptions, and frozen baselines. +- `build-binaries.sh`, `build-coding-agent-bundle.mjs`, `package-workspaces.mjs`: platform binaries, product bundles, and package outputs. +- Helpers such as `diff-model-catalog.mjs` and `generate-thinking-capabilities.mjs`: catalogs and capabilities. Model-snapshot generators live in providers' `scripts/`. +- `*.test.mjs`, `guard-self-tests.test.mjs`, `__fixtures__/`: script regressions and guard self-tests. `smoke/`: controlled terminal validation. + +## Boundaries and invariants + +- Extend existing scripts and root commands rather than create parallel check systems. Resolve paths from script / repository locations and support documented invocation directories. +- Fix implementations when guards fail. Do not broaden exemptions, remove fixtures, or refresh baselines to conceal boundary violations. Justify legitimate rule changes and cover both valid and invalid cases. +- Distinguish real source scans, tracked-tree / staged checks, and synthetic self-tests. New files must not escape validation because they are not yet tracked. +- Register new workspaces in all three sources. Keep exact dependency versions and lockfiles consistent with dependency changes; respect existing commit checks and do not skip hooks. +- Put temporary experiments in temporary directories and persistent outputs in established locations such as `dist/` / `.artifacts/`. Clean up only directories you created and can verify ownership of. +- Use structured subprocess arguments and check exit statuses. Separate protocol stdout from diagnostics; never log real credentials or complete sensitive environments. +- Public release tooling provides only existing local build capabilities. Do not add private uploads, endpoints, or protected-tag operations here. +- Check task scope before dependency installs, remote catalog refreshes, or publication commands. Documentation / guard tasks must not also modify user resources or generate large unrelated outputs. + +## Validation and documentation + +- Run root `pnpm run test:scripts`. Guard changes also run the corresponding real scan and `--self-test`; code changes run the full `pnpm run check`. +- For shell changes, run `bash -n `, then offline fixtures / dry-runs to verify actual arguments and failure paths. +- Keep root commands, CI, and [contribution requirements](../CONTRIBUTING.md) consistent. Update the relevant rules when changing layers or public boundaries. From 116686d993fda769f2f62a9f5709f0947956690a Mon Sep 17 00:00:00 2001 From: ZouR-Ma <2605315944@qq.com> Date: Thu, 15 Oct 2026 11:05:00 +0800 Subject: [PATCH 5/7] docs: define development and testing practices --- docs/AGENTS.md | 1 + docs/development.md | 72 +++++++++++++++++++++++++++++++++++++++++++++ docs/testing.md | 56 +++++++++++++++++++++++++++++++++++ 3 files changed, 129 insertions(+) create mode 100644 docs/development.md create mode 100644 docs/testing.md diff --git a/docs/AGENTS.md b/docs/AGENTS.md index b2688d31..495ce6b8 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -4,6 +4,7 @@ Inherits the [root rules](../AGENTS.md). This directory maintains repository-wid ## Responsibilities and entry points +- `development.md`, `testing.md`: coding conventions, collaboration, failure handling, and validation selection. - `step-configuration.md`, `step-unified-config-and-mcp.md`: configuration, directories, trust, and MCP startup / write contracts. - `command-permissions.md`: command analysis and product approvals. `orchestration-lifecycle.md`, `goal-lifecycle.md`: orchestration and goal lifecycles. - `tui-rendering-pipeline.md`, `step-goal-ui.md`: CLI UI and terminal rendering integration. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..26580732 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,72 @@ +# Development and collaboration guide + +This guide adds coding and collaboration practices to the [root agent instructions](../AGENTS.md). Module responsibilities remain in their local `AGENTS.md` files; [CONTRIBUTING.md](../CONTRIBUTING.md) owns submission and review requirements, and [testing.md](testing.md) explains validation selection. + +## Environment and source of truth + +- Use Node.js `>=22.19.0` and the pnpm version declared in the root [manifest](../package.json). Install locked dependencies with `pnpm install --frozen-lockfile --ignore-scripts`. +- Verify behavior against current source, installed dependency types, manifests, and tests. Research and historical design notes do not establish current behavior. +- Read the root and affected local instructions before editing. Check working-tree state and keep the change within the agreed scope. +- Root `pnpm run check` applies Biome fixes to its configured files, then runs type and repository checks. Inspect the resulting diff; a successful command does not imply tests ran. + +## Coding conventions + +### Names and abstraction + +- Follow the surrounding module's naming and file organization. New TypeScript files normally use kebab-case, types / classes use PascalCase, and functions / variables use camelCase; preserve existing public names and external field spellings. +- Keep a function at one abstraction level. Extract a helper when it owns a distinct operation, policy, or reusable behavior; avoid wrappers that merely forward a single call without adding meaning. +- Use options objects when parameters form a meaningful configuration or need clear names. Do not wrap a single internal parameter only for stylistic uniformity. +- Group checks for the same execution phase and collect useful failure context once. Avoid scattered guards and duplicate logs for the same error. +- Preserve the difference between an absent property and an explicitly supplied value. Choose direct optional properties or conditional spreads according to merge, serialization, and caller semantics, not a blanket style rule. +- Reuse existing primitives, registries, keybindings, themes, and feature interfaces. Do not introduce a parallel mechanism or change public exports just to simplify a local implementation. + +### Types and validation + +- Keep the existing [strict compiler settings](../tsconfig.base.json). The [Biome configuration](../biome.json) currently permits explicit `any`; that permission is not a reason to erase useful types in new code. +- Parse untrusted JSON, configuration, model/tool inputs, durable files, and process/wire data as `unknown`, then narrow at the owning entry point. Validate fields and failure behavior required by consumers. +- Do not repeat runtime validation solely because a typed same-process interface could theoretically receive an invalid value. Validate where data actually enters from an untyped or independently evolving source. +- Prefer discriminated unions for distinct outcomes and narrow before accessing fields. Handle all variants of a closed union; use an intentional, documented fallback for extensible or versioned external input. +- An unavoidable `any`, assertion, or non-null assertion needs a narrow scope and a reason that explains the guarantee or dependency limitation. Do not use `as unknown as`, disabled diagnostics, or a widened type merely to conceal an incompatible value. +- Check optional-value semantics before changing signatures: absence, `undefined`, `null`, an empty string, and an empty collection can have different meanings in configuration and protocols. + +### Comments and public interfaces + +- Use comments and JSDoc for non-obvious behavior, preconditions, returned results, errors, cancellation, timing, and resource ownership. Public callers must be able to understand the obligations they rely on. +- Do not narrate obvious control flow, repeat nearby types, or keep an implementation conversation in source comments. Keep explanations close to the code they govern. +- Update owning documentation when behavior or public interfaces change. Keep one authoritative description and link related guides rather than duplicate API definitions or defaults. + +## Failure handling and asynchronous ownership + +- Identify the layer that owns an error: lower layers preserve actionable cause information, while the caller that can recover or present the failure decides what happens next. Avoid logging the same failure independently at every layer. +- Invalid configuration, missing required references, and unknown mutation outcomes must not silently become empty results or success. Stop work that depends on an untrusted state and report what remains uncertain. +- Preserve independent outcome facts. A command can time out and still exit with code zero after trapping a signal; report timeout, signal, and exit status independently under the existing result contract. +- Do not automatically retry side-effecting operations after cancellation, connection loss, or persistence failure without knowing whether they already executed. Read-only or idempotent retries still need a bounded policy and cancellation. +- A best-effort catch must explain why ignoring the failure is safe. Cleanup failures or abandoned-promise rejections may be intentionally contained; configuration failures and data loss must remain visible. Do not broaden the protected block beyond the operation being contained. +- Give background work an owning run or session, observe its rejection, and settle it on cancellation or replacement. Session-wide idle or completion events do not automatically identify the result of one queued message. +- Teardown closes publication / listener paths, requests cancellation, waits for owned work or child exit, and releases timers, subscriptions, locks, and temporary resources. An abort request alone is not proof that teardown finished. +- Late callbacks must check their owning lifecycle before publishing state. Do not let a completed operation update a replacement session or reopen a canceled run. +- Commit durable state before publishing notifications or deriving UI/cache state. A failed write must not leave consumers observing a success that was never persisted. +- Reuse existing process and storage helpers. Cleanup of a possible symlink or junction must remove the link rather than recursively traverse its target; recursive deletion is limited to known owned directories. +- If a listener failure is intentionally contained, report it without starving later listeners, and ensure the owner handles any partial state it changed. Catching an exception does not restore state by itself. + +## Collaboration workflow + +Use this workflow when several contributors or agents work on the same change. A single-contributor task uses the same scope and verification rules without unnecessary coordination overhead. + +1. **Define the result.** Agree on behavior, constraints, affected consumers, and acceptance evidence. Continue already authorized work; clarify only decisions needed to resolve an actual ambiguity. +2. **Assign ownership.** Name the module and file paths each contributor owns, plus one integration owner. Everyone must know other changes may be present in the checkout. +3. **Agree shared interfaces first.** Establish request / result fields, error and cancellation semantics, and persistence or event changes before dependent implementations diverge. Assign one owner to coordinated changes in public types, exports, manifests, and the lockfile. +4. **Work independently within the assigned files.** Use a suitable existing checkout for sequential work. Isolate overlapping concurrent edits in separate worktrees when needed; do not create a worktree for every task automatically or stash / revert another task's changes. +5. **Validate and hand off.** Report changed files, behavior and interface effects, exact commands and results, remaining failures, and unresolved assumptions. Keep temporary working notes local; they are not product documentation or material to stage. +6. **Integrate and review.** The integration owner reviews the combined diff, checks dependent callers, resolves owned conflicts, and selects validation for the final combined tree. Stop a Git operation if its conflicts extend into unrelated work; do not discard that work to finish the task. + +An interface change must reach dependent contributors before they continue against an obsolete definition. Independent implementation work can proceed while such a decision is pending. Keep durable design rationale in the owning product documentation, not a transcript of agent messages. + +## Git and review workflow + +- Follow the English text and Conventional Commit requirements in [CONTRIBUTING.md](../CONTRIBUTING.md#commit-and-pr-conventions). Separate commits by coherent responsibility; do not manufacture extra commits or mix unrelated refactors into a fix. +- Commit and push only within the user's authorization, using the current human Git identity and explicit staging paths. Inspect staged content, formatter changes, and metadata before publishing. +- By default, update published task branches with normal commits. Rewrite their history only when explicitly requested; record the live remote OID and use an exact `--force-with-lease` so another contributor's update rejects the push. Never use raw `--force` or rewrite an unrelated branch. +- After a rewrite, verify remote HEAD and revisit review comments and CI tied to previous commits. Earlier hashes or inline anchors are not current evidence. +- Use the [PR review checklist](../CONTRIBUTING.md#pr-review-checklist). Explain compatibility changes, affected consumers, prompt behavior, validation, and limitations without reproducing the implementation history. +- Report only checks actually run. New changes, unresolved failures, changed artifacts, or relevant environment changes justify new validation; commit or push alone does not. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 00000000..28e0ac3c --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,56 @@ +# Testing policy + +Select evidence for the behavior being changed, using existing suites and fixtures. [CONTRIBUTING.md](../CONTRIBUTING.md#before-submitting-a-pr) owns the repository-wide pre-submission requirements; local module rules list more focused entry points. + +## Selecting checks + +Run root `pnpm run check` for code changes. It includes formatting fixes, types, imports, dependency and layer checks, frozen entry points, public boundaries, and a browser bundle smoke; it does not run tests. + +| Changed behavior | Focused evidence and starting points | +| --- | --- | +| Documentation and agent instructions | Verify links, source paths, command names, and stated behavior; run `git diff --check` and root `pnpm run check:public-boundary` after staging new files. | +| Guards and build scripts | Run root `pnpm run test:scripts`, the affected real guard, and its `--self-test` where supported. Cover both valid and rejected inputs. | +| Agent Loop, session, or compaction | Select agent-core tests and its `vitest.harness.config.ts` suite. Product session changes use the [coding-agent suite harness](../packages/coding-agent/test/suite/README.md), including cancellation, event order, queues, recovery, and replacement. | +| Permissions and command execution | From `packages/coding-agent`, start with `pnpm exec vitest --run test/step-permissions.test.ts test/step-command-policy-uncertainty.test.ts test/step-run-command-timeout.test.ts`; add affected command and persistence regressions. | +| Providers and model access | From `packages/providers`, select mock / faux and protocol conformance tests, such as `pnpm exec vitest --run test/dialect-provider-registry.test.ts test/faux-provider.test.ts`, with no real credentials. | +| CLI startup and protocol modes | From `apps/cli`, select `test/package-command-paths.test.ts` and affected startup tests. From `packages/coding-agent`, select `test/rpc-jsonl.test.ts`, `test/rpc-prompt-response-semantics.test.ts`, and SDK tests for affected consumers. | +| UI, keyboard input, or terminal rendering | From `apps/cli`, run `pnpm exec vitest --run test/tui-acceptance-snapshot.test.ts` and affected components. From `packages/tui`, use `node --test test/.test.ts`, covering narrow screens, resize, focus, overlays, CJK, ANSI, and both screen modes as applicable. | +| Public exports, package entry points, or release artifacts | Inspect manifests and guards, build affected outputs from current source, and test the actual artifact under its intended launcher. For release bundle logic, run root `node --test scripts/release-bundle.test.mjs`. | + +During development, run the focused checks that cover the changed behavior. Before submitting or updating a PR, follow the existing repository-wide `npm run check` and `./test.sh` requirements; do not repeat unchanged passing evidence solely to create another commit or push. + +Documentation-only work does not introduce dependency changes, provider-data refreshes, or real model calls. Build only when the selected validation consumes artifacts; `./test.sh` may perform its offline build when outputs are missing. + +## Fixtures, source execution, and artifacts + +- Prefer existing owning test files over one new file per assertion. Add a regression that fails the old defective behavior and passes the fix; assert behavior at the meaningful caller, not a duplicate of implementation branches. +- For coding sessions, use `test/suite/harness.ts` and the faux provider as specified by the [suite rules](../packages/coding-agent/test/suite/README.md). Mock nondeterministic boundaries such as model streams, networks, clocks, or child processes while retaining the real runtime and consumer path being tested. +- Some workspace tests import package entry points that resolve to ignored `dist/` files. The root [test wrapper](../test.sh) builds offline when required outputs are absent, but presence alone does not prove freshness. Refresh outputs affected by a code change before treating artifact-based tests as current evidence. +- Keep source-launch tests explicit about their subject and launcher. Source tests can verify development resolution; they do not substitute for a built entry-point smoke. Conversely, do not force a test of source resolution through an artifact. +- Test the actual CLI, RPC, SDK, or tool consumer when the change crosses that entry point. A helper-only mock cannot demonstrate correct startup, framing, exit status, or consumer interpretation. +- Default tests use fake accounts, fixtures, temporary resources, and keyless providers. Real-API tests require an explicit task scope and separate evidence; never enable them accidentally through inherited credentials. + +## Assertions and expected output + +- Assert observable effects: reread files, persisted session entries, actual protocol output, registered tools, and cleanup results. An agent's claim of success is not sufficient evidence. +- Verify unaffected resources remain unchanged when the operation is scoped. Test failure paths for partial writes, uncertain execution, cancellation, retries, and replay as applicable. +- Prompt, tool-description, schema, and model-visible output changes affect agent behavior. Name the receiving modes and users, and use the existing faux-session or snapshot facilities to verify the intended request / response behavior. +- Update UI snapshots only for an intentional visible change and review the full diff. Do not regenerate baselines merely to hide a regression; normalize only genuinely variable data, never fields that carry behavior. +- A guard regression must demonstrate that the invalid input is rejected. Green scans over valid source alone do not establish that a new rule catches violations. +- Do not assert private helper structure or timing accidents when the public behavior is the requirement. Keep clocks and ordering controlled instead of adding arbitrary sleeps. + +## Concurrent resources and teardown + +- Each test owns the ports, directories, external namespaces, timers, listeners, and child processes it acquires. Use isolated fixtures and unique temporary paths rather than shared predictable names or fixed ports. +- Settle resources in teardown even after assertion failure, timeout, or retry. Abort or kill owned work, wait for exit, remove listeners and timers, release locks, and clean only verified owned paths. +- Keep IPC paths within platform limits and distinguish host sandbox restrictions from product failures. A host limitation requires recorded evidence; it is not a reason to remove an assertion or bypass a product permission check. +- Tests must work in the suite's supported parallel execution. A case passing alone but failing alongside others needs investigation into shared state, resource ownership, synchronization, and timeout budgets. +- Results apply to the platforms actually tested. macOS or Linux success does not demonstrate Windows behavior for shells, path handling, native helpers, or installers. + +## Handling failures and reporting evidence + +Record the exact command, selected test count, failure, and environment before changing anything. Classify the failure as changed behavior, an existing defect, stale artifacts, shared-state nondeterminism, a missing platform capability, or a host restriction using evidence from the failing path. + +Run a focused reproduction when it resolves an uncertainty. A successful isolated retry does not by itself establish why the suite failed; retain the failure evidence and repeat the affected combined path after fixing or confirming the cause. Do not weaken checks, enlarge timeouts without a justified budget, or relabel an unexplained failure as infrastructure. + +Report commands actually run, outcomes, relevant platforms, intentional skips, and remaining failures. The root CI [workflow](../.github/workflows/ci.yml) currently builds, checks, and tests on Linux with Node 22; do not claim a broader local or CI matrix than exists. Report queued or running CI as pending. From b38fc6e32d07ae50b5345b29e7ea6ea15d69a1b5 Mon Sep 17 00:00:00 2001 From: ZouR-Ma <2605315944@qq.com> Date: Thu, 15 Oct 2026 11:05:05 +0800 Subject: [PATCH 6/7] docs: map repository structure and engineering rules --- AGENTS.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b96f24b9..cda505ec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,49 @@ This file defines repository-wide rules for Step-Code. Before changing a directo - Organize architecture guidance around layers, responsibilities, and ownership. Verify paths, dependencies, commands, and defaults against current source, `package.json`, check scripts, and the relevant documentation. - Check implementation status before borrowing designs from other repositories. Do not copy obsolete paths, unimplemented plans, or private branch and release procedures. -## 2. Layers and module entry points +## 2. Project structure and dependency layers + +The current source layout is: + +```text +apps/ + cli/ Process entry points and interactive host + src/args/ Arguments and mode selection + src/bootstrap/ Startup composition + src/commands/ Top-level commands + src/modes/ Mode routing + src/bun/ Standalone binary entry + src/ui/ UI host, runtime, and views +packages/ + agent-core/ Generic Agent runtime + src/harness/ Sessions, context, compaction, and generic tools + src/search/ Generic search + coding-agent/ Coding product and SDK + src/core/ Product session mechanisms, tools, and extensions + src/features/ Plan, task, subagent, workflow, goal, and cron + src/step/ Step configuration, permissions, MCP, and integrations + src/modes/ Non-interactive execution + src/server/ Host service adapters + src/theme/ Product themes + src/render/ Rendering helpers + src/components/ Reusable product components + docs/ Package APIs and usage + examples/ SDK and extension examples + test/ Product and session regressions + config/ Product-neutral startup migrations + contracts/ Independent host interfaces and wire frames + providers/ Model access, adapters, catalogs, and credentials + telemetry/ Telemetry contracts and reference implementations + tui/ Terminal input, layout, and rendering +docs/ Repository-wide guides and runtime contracts +scripts/ Checks, generators, builds, and development tools +infra/release/ Local packaging and installer templates +plugins/ Built-in marketplace and plugin declarations +.github/ Public CI workflows and contribution templates +.husky/ Git hook definitions +``` + +Package manifests and `scripts/workspace-registry.json` define workspace membership; build outputs and installed dependencies are not source modules. Read the [development and collaboration guide](docs/development.md) for implementation practices and [testing policy](docs/testing.md) to select validation. Dependencies flow from product entry points toward foundational capabilities. Foundational packages must not depend on products or applications. The table defines allowed internal dependencies, not a requirement to depend on every listed package. @@ -65,6 +107,11 @@ Dependencies flow from product entry points toward foundational capabilities. Fo - Relative TypeScript imports use `.ts` extensions and follow `check:ts-imports`. Source checked by the root configuration uses erasable syntax; do not add `enum`, parameter properties, or syntax requiring JavaScript emit. - Do not hand-edit `packages/providers/src/models.generated.ts` or provider data snapshots. Change generator scripts or inputs, then run the corresponding generation commands. - Preserve existing features and explicit user requirements. Do not delete functionality, weaken checks, or introduce unrelated refactors to make type or boundary checks pass. +- Keep functions at one abstraction level; introduce helpers only when they own a meaningful operation, policy, or reusable behavior. +- Validate external JSON, configuration, persisted data, and protocol inputs at their entry points. Narrow `unknown`; justify unavoidable `any` and type assertions rather than weaken checks or duplicate validation at every typed internal call. +- Comments and JSDoc explain non-obvious behavior, failure, cancellation, and resource ownership; do not restate code or record an implementation conversation. +- Handle failures at an explicit owner. Do not silently ignore invalid configuration, uncertain outcomes, or partially completed mutations. Best-effort catches must explain why ignoring the error is safe. +- Cancellation and teardown must settle owned work, release resources, and prevent late callbacks from publishing into replaced sessions; requesting an abort alone does not prove cleanup completed. ## 5. Development and validation @@ -72,19 +119,21 @@ Dependencies flow from product entry points toward foundational capabilities. Fo - Pin direct external dependencies to exact versions. Update the lockfile with dependency changes; do not update dependencies for documentation tasks or bypass lockfile commit checks. - Run source through root `pnpm step` or `./step-test.sh`. `./step-test.sh --no-env` removes listed provider environment credentials, but local user resources still require care. - After code changes, run root `pnpm run check`, inspect the full output, and fix errors. It includes Biome autofixes, type checks, and boundary checks; it does not run tests. -- Run relevant tests when changing tests. Run Vitest from the owning package with `pnpm exec vitest --run `; tui uses `node --test test/.test.ts`. +- Select tests for changed behavior using the [testing policy](docs/testing.md). Run Vitest from the owning package with `pnpm exec vitest --run `; tui uses `node --test test/.test.ts`. - Use `./test.sh` for repository tests and follow the pre-submission requirements in [CONTRIBUTING.md](CONTRIBUTING.md). It isolates user resources and credentials and builds offline if outputs are missing. Do not run a full Vitest suite that may activate real providers directly. - Unit and regression tests use faux providers, fixtures, mocks, and temporary directories. They must not read real accounts or consume paid model requests. -- For documentation-only changes, verify relative links, directories, and commands and run `git diff --check`. Documentation changes alone do not require builds or model tests. +- For documentation-only changes, verify relative links, directories, and commands and run `git diff --check`; follow the repository-wide pre-submission checks in `CONTRIBUTING.md`. Build only when a selected check needs artifacts; do not introduce real model calls for documentation validation. - When changing Agent Loop, sessions, tool permissions, providers, themes, or cross-process contracts, update the relevant `docs/`, package documentation, and affected `AGENTS.md` files. ## 6. Task execution and Git collaboration - Before editing, read affected files, local rules, and relevant documentation. For complex or high-risk work, explain steps, tools, acceptance criteria, and rollback. Continue reversible work already authorized by the user. +- For concurrent work, name module and file owners, agree shared interfaces first, and assign one integration owner. Coordinate edits to public types, exports, manifests, and the lockfile; hand off changed behavior, validation results, and remaining issues using the [collaboration workflow](docs/development.md#collaboration-workflow). - Prefer existing tools in `scripts/`. Keep temporary validation scripts in temporary directories, outside product source. - Do not commit or push unless requested. Stage only explicit paths belonging to the task; do not use `git add .` or `git add -A`. - If the working directory contains another task's changes, use a separate worktree or touch only your files. Do not stash, clean, or revert other contributors' changes. -- Do not use `git reset --hard`, `git checkout .`, `git clean -fd`, skip hooks, or force-push. If a Git operation conflicts with unrelated files, stop that operation and explain the conflict. +- Do not use `git reset --hard`, `git checkout .`, `git clean -fd`, skip hooks, or raw `--force`. Rewrite a published task branch only when explicitly requested; record its live remote OID, use an exact `--force-with-lease`, and abort on remote movement. If a Git operation conflicts with unrelated files, stop that operation and explain the conflict. +- Write commit subjects and bodies, PR/MR titles and descriptions, public issues, and review comments in English. Commit and PR/MR titles follow Conventional Commits; split commits by coherent responsibility, not to inflate the history. - Commits, PR/MR descriptions, issues, and comments must not include AI-client attribution, bot co-authors, or generated-by footers. Keep author / committer as the current human contributor's Git identity. - Report the changes, validation evidence, and anything still unverified. Keep delivery notes concise and specific. From a90bfa5feb775d6bcf905bea1bb2b3c8787986c2 Mon Sep 17 00:00:00 2001 From: ZouR-Ma <2605315944@qq.com> Date: Thu, 15 Oct 2026 11:05:05 +0800 Subject: [PATCH 7/7] docs: standardize English commits and pull request reviews --- .github/pull_request_template.md | 19 +++++++++++++++++++ CONTRIBUTING.md | 23 +++++++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..2766e554 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## Problem + + + +## Changes + + + +## Behavior and compatibility + + + +## Validation + + + +## Limitations + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 732f9bb2..2bbafca1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,6 +44,27 @@ If you ignore this document twice, or if you spam the tracker with agent-generat If you send a large volume of issues through automation, your GitHub account will be permanently blocked. No taksies backsies. +## Commit and PR Conventions + +Write commit subjects and bodies, PR/MR titles and descriptions, public issues, and review comments in English. Commit and PR/MR titles follow Conventional Commits: `type(scope): summary`, with an optional scope. Use a concrete summary such as `fix(session): preserve queued input after cancellation`. + +Keep each commit focused on one coherent responsibility. Separate independent changes so reviewers can inspect them; do not add empty or artificial commits to increase the count. The author and committer remain the human contributor, as required by the attribution policy above. + +Follow the [development and collaboration guide](docs/development.md) for coding practices, concurrent ownership, error handling, and Git workflow. Use the [testing policy](docs/testing.md) to select behavior-level evidence while developing. + +## PR Review Checklist + +Use the [PR template](.github/pull_request_template.md) and replace its guidance with concrete evidence. Scale the description to the change, and explain any section that does not apply. + +- State the problem and resulting behavior. For bugs, include a reproducible trigger and explain the root cause. +- Identify affected modules, public consumers, and changes to previously accepted inputs: configuration keys, environment variables, CLI arguments, provider responses, persisted sessions, RPC/SDK calls, and extension hooks. +- For a changed default, removed fallback, or narrowed branch, describe who used the old behavior and their migration or escape path. A refactor accounts for the old path's feature inventory rather than silently losing it. +- Treat system prompts, tool descriptions, reminders, and model-visible output as behavior. State who receives changed text, what it controls, and how the new behavior is verified. +- Review public interfaces at both producer and consumer sides. Check old session data and error / cancellation behavior where relevant; document intentional compatibility changes. +- Include exact validation commands and results, relevant platforms, and any skipped or unverified cases. Report pending CI as pending; a passing unit test alone does not prove a built CLI or protocol entry point works. +- Explain user-visible snapshot changes and verify actual files, persisted state, or protocol output rather than only an agent's success message. +- Confirm the diff contains only intended files, public examples use neutral data, and temporary handoff notes, private infrastructure, credentials, and AI attribution are absent. + ## Before Submitting a PR Before submitting a PR: @@ -55,6 +76,8 @@ npm run check Both must pass. +These are repository-wide submission checks. During development, run focused checks for the changed behavior; do not repeat a passing check solely because a commit or push follows, unless files or relevant inputs changed. Inspect any modifications made by the formatter before staging or publishing. + If you are adding a new provider to `packages/providers`, see `AGENTS.md` for required tests. ## Questions?