# xcode

**Repository Path**: xywhsoft/xcode

## Basic Information

- **Project Name**: xcode
- **Description**: 一个基于浏览器的 AI 代码编写 Agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xcode v2

`xcode` is a practical C coding-agent CLI built on the sibling `xrt`, `xllm`, and `xwork` repositories.

The v2 mainline starts with a focused product loop: resume a durable session, stream a reasoning model, execute workspace tools, delegate bounded read-only investigations, compact long context transactionally, and continue until the requested development task is verified. The previous broad implementation remains under `dev/v1` for reference.

## Stack

```text
xcode             CLI, config, terminal rendering, interactive chat, Ctrl+C
  -> xwork         agent loop, tools, policy, artifacts, compaction scheduling
    -> xllm-session context ledger, token budgets, journal/recovery, quality-gated compaction
    -> xllm-memory  layered, namespaced, provenance-preserving long-term records
      -> xllm       provider request, HTTP streaming, SSE/tool-call normalization
        -> xrt      core HTTP/1.1/TCP/TLS, filesystem, subprocess, platform runtime
```

All four layers are C. HTTP/2 is intentionally outside the current milestone.

## Default GLM Coding Plan profile

The default profile uses:

- endpoint: `https://open.bigmodel.cn/api/coding/paas/v4`;
- model: `glm-5.2` with the built-in `glm-5.2-coding` capability profile;
- context window: 1,000,000 tokens;
- maximum output: 131,072 tokens;
- output reserve: 65,536 tokens, separate from the per-call maximum;
- safety reserve: dynamic 3%, clamped to 8K–32K (30K at this window);
- input budget: 904,464 tokens after output and safety reserves;
- per-call `max_tokens`: dynamically capped by the remaining context, while short requests retain the full 131,072-token ceiling;
- soft tool-output pruning at 75% pressure;
- transactional summary compaction at 95% pressure, with an eight-section quality gate and one corrective retry;
- separate Memory and Knowledge retrieval, each bounded to 8 hits / 16 KiB and audited by store revision;
- default memory sensitivity ceiling `internal`, excluding `sensitive` and `secret` records;
- no hard Agent-turn limit;
- 64 KiB inline tool output, with larger results saved under `.xcode/artifacts`;
- transactional multi-file patching, managed long-running processes, structured permissions, and tool hooks;
- a default completion gate that requires a successful verification command after the latest write;
- incremental session journal plus atomic checkpoints for process-crash recovery.
- dynamic tool discovery plus MCP 2025-06-18 stdio clients with namespaced,
  source-owned proxy tools and bounded messages/tool counts.
- up to 4 read-only delegations per parent run by default, each isolated to a
  fresh session with an 8-turn, 120-second, 16K-output-token, 64 KiB result
  budget and no recursive delegation.

The Coding Plan endpoint and model limits follow Zhipu's current [Coding Plan Cline guide](https://docs.bigmodel.cn/cn/guide/develop/cline) and [chat-completions API reference](https://docs.bigmodel.cn/api-reference/%E6%A8%A1%E5%9E%8B-api/%E5%AF%B9%E8%AF%9D%E8%A1%A5%E5%85%A8). Hosts may select another built-in profile or use `profile: "none"` for an explicitly configured custom model; `doctor` reports custom models as ungoverned.

## Build

From this repository on Windows with GCC available:

```bat
build.bat
```

On Linux or macOS with the sibling repositories next to this one:

```sh
sh build.sh
```

The POSIX build accepts `CC`, `CFLAGS`, `LDFLAGS`, `LIBS`, `XRT_DIR`, `XLLM_DIR`,
and `XWORK_DIR`. Set `RUN_TESTS=0` for a cross build whose binaries cannot run on
the build host.

The build uses `-Wall -Wextra -Werror -O2`, links all four current sibling
mainlines, and validates `version`, `help`, config-driven `status`, the complete
four-layer tool loop, and a deterministic resilience suite. The latter drives
xcode against its own source tree with a local HTTP/1.1 provider, then covers a
429 retry, strict malformed-SSE rejection and durable continuation, a 64-request
session, hard timeout, provider business-code preservation (including
non-retryable account policy restrictions), and offline replay of successful
and failed runs.

`xcode-xrt.h` is the single-header module profile for the complete stack. The
build links one XRT implementation object and does not depend on `xhttp`.

GitHub Actions runs the same gate on Windows, Ubuntu, and macOS. The sibling
repository URLs and refs can be pinned with the `XRT_REPOSITORY`,
`XLLM_REPOSITORY`, `XWORK_REPOSITORY`, `XRT_REF`, `XLLM_REF`, and `XWORK_REF`
repository variables. Pin all three refs together when validating an
unreleased cross-repository change.

## Configure authentication

The key is resolved in this order:

1. the environment variable named by `provider.api_key_env` (default `ZHIPU_API_KEY`);
2. `GLM_API_KEY` as a compatibility fallback;
3. `.xcode/secrets.local.json` in the workspace.

Example environment setup in PowerShell:

```powershell
$env:ZHIPU_API_KEY = Read-Host "Zhipu API key"
```

Example local secret file (automatically ignored when it is under the xcode repository root; project repositories should also ignore it):

```json
{
  "api_key": "your-key"
}
```

The CLI never prints the key. An owned in-memory copy is cleared when the app shuts down.

Copy [xcode.config.example.json](xcode.config.example.json) to `<workspace>/.xcode/config.json` to customize the provider profile, budgets, persistence, memory policy, approval policy, and loop guards. Command-line options override the file.

Agent profiles are separate from model capability profiles:

- `coding` is the default autonomous implementation profile;
- `plan` inspects with read-only tools and returns an implementation plan;
- `review` performs an evidence-driven read-only code review;
- `custom` requires an explicit `agent.system_prompt` or `--system-prompt`.

`plan` and `review` enforce the read-only approval ceiling; conflicting
`--auto` or `--ask` settings are rejected instead of silently weakening the
profile. Select a profile with `agent.profile` or `--agent-profile`.

The `delegate_readonly` tool is enabled by default for every Agent Profile.
Each call assigns one precise investigation to a fresh depth-1 child session.
The child borrows the provider, root cancellation context, workspace, and
filtered Memory/Knowledge access, but receives only `read_file`, `list_files`,
and `search_text`. It cannot modify files, execute commands, create artifacts,
persist a session, access `.git`/`.xcode` internals, or delegate again. Its
bounded `xcode.subagent.result.v1` report is returned as one parent tool result.

Configure the ceiling under `subagents` or with `--subagent-max-calls`,
`--subagent-timeout`, `--subagent-max-turns`, `--subagent-max-output`, and
`--subagent-max-final-bytes`; `--no-subagents` removes the tool entirely.

MCP stdio servers are configured under `mcp.servers`. `program` and
`arguments` are passed directly without a shell; relative program paths and
working directories are resolved from the workspace. Required servers fail
the run during startup, while optional servers emit a warning and leave the
remaining registry usable. Remote annotations are treated as untrusted by
default, so configure `default_effect` conservatively and only enable
`trust_read_only_annotations` for a server you control.

## Use

One-shot autonomous run:

```powershell
build\xcode.exe run -C D:\GIT\project -- "Analyze the project, implement the requested feature, run tests, and fix failures."
```

Interactive session that resumes the same context:

```powershell
build\xcode.exe chat -C D:\GIT\project
```

The chat loop supports `/stats`, `/profile`, `/tools`, `/mcp`, `/continue`,
`/compact`, and `/multiline` (terminated by `/end`) in addition to `/exit`.

For automation, a prompt may come from redirected stdin or `--input PATH`.
`--input-format json` accepts one `{"prompt":"...","id":"..."}` object;
`jsonl` accepts one such object per line and runs them sequentially in the same
durable session. `--format json` emits one `xcode.result.v1` object, while
`--format jsonl` emits one result record per request. Model text streaming is
suppressed in structured modes, but the optional `--events` audit stream still
records the full lifecycle.

```powershell
build\xcode.exe run -C D:\GIT\project --input requests.jsonl --input-format jsonl --format jsonl --auto
```

Inspect effective configuration and persisted context without calling the provider:

```powershell
build\xcode.exe status -C D:\GIT\project
```

Validate workspace access, provider configuration, token budgets, authentication source,
artifact storage, and durable-session recovery without sending a model request:

```powershell
build\xcode.exe doctor -C D:\GIT\project
```

Force a real model-generated summary checkpoint and atomically persist the compacted session:

```powershell
build\xcode.exe compact -C D:\GIT\project
```

Resume a process-interrupted run without appending the user prompt a second time:

```powershell
build\xcode.exe continue -C D:\GIT\project
```

`status` reports `continuation: pending_tools`, `model`, or `idle`. Use `continue` for the first two states. Pending side effects have at-least-once recovery semantics: if a tool completed but its result was not journaled before the process stopped, policy checks run again and the call may be retried.

Useful controls:

- `--new-session` starts fresh instead of recovering `.xcode/session.json` and its journal;
- `--session PATH` selects a different durable session;
- `--show-reasoning` renders reasoning deltas to stderr;
- `--events PATH` writes a secret-redacted `xcode.event.v2` JSONL audit stream with run/sequence IDs, content hashes, provider fingerprints, usage, timing, transport, operation-context diagnostics, compaction-quality reports, and memory-retrieval receipts;
- `replay --events PATH` validates a recording offline without provider credentials or tool execution;
- `--ask` requires terminal confirmation for writes and commands;
- `--read-only` rejects writes and commands;
- `--max-turns N` adds an explicit hard cap; `0` remains unlimited;
- `--no-subagents` disables delegation; otherwise each parent request gets a
  fresh call budget and structured output reports child calls/model turns;
- `compact` (or `/compact` in chat) forces a safe-prefix summary checkpoint for continuation testing;
- `continue` recovers an interrupted model/tool loop without duplicating user input;
- Ctrl+C cancels the root token shared by xwork, xllm retry/backoff, and the XRT core HTTP transport.

`exec_command` is a real shell process whose working directory starts inside the workspace; it is not an OS sandbox. Use `--ask` or `--read-only` when commands are not fully trusted.

## Current milestone boundary

Implemented now: a stable parent-agent coding loop with bounded read-only child delegation, journal-backed crash recovery, durable multi-turn chat, coding/plan/review/custom Agent Profiles, JSON/JSONL input and result output, governed model capability profiles, dynamic long-context handling, quality-gated compaction, layered auditable Memory/Knowledge retrieval, eleven workspace/process tools, a source-aware dynamic tool registry, MCP stdio discovery/calls, transactional patch rollback, structured permission and hook boundaries, write-after-verification completion gating, depth-aware secret-redacted event v2 recording and offline replay/evaluation, cross-layer cancellation/deadline diagnostics, artifacts, and safe configuration/secret handling.

Deferred until later Phase 3 milestones: richer TUI/IDE surfaces, explicit memory-management commands and extraction policy, MCP Streamable HTTP, parallel/remote workers, and write-capable multi-agent scheduling.