writing-agent

writing-agent is a report-writing and export platform focused on:

• structured generation flows (planner / writer / reviewer / qa)
• citation-aware RAG retrieval and trust checks
• document export pipelines (Markdown and DOCX)
• web workbench with streaming editing
• governance scripts for quality, release, and operations

Project Layout

.
|- writing_agent/                       # Python application and web backend
|  |- web/                              # FastAPI app + templates + frontend assets
|  |- v2/                               # Graph pipeline and generation runtime
|  |- llm/                              # LLM provider abstraction layer
|  |- state_engine/                     # State/route/replay runtime modules
|- engine/                              # Rust editor/render core workspace
|- gateway/                             # Node AI gateway
|- tests/                               # Unit / integration / e2e / ui tests
|  `- fixtures/                         # Versioned sample inputs and golden fixtures
|- scripts/                             # Guardrails, release, and ops scripts
|- docs/                                # Architecture and runbooks
|- security/                            # Policy-as-code configs
|- templates/                           # Prompt and few-shot assets
|- infra/                               # Terraform resources
|- .data/                               # Local-only runtime outputs (ignored)
|- pyproject.toml                       # Python packaging metadata
|- requirements.txt                     # Runtime dependencies
`- requirements-dev.txt                 # Development dependencies

Local hygiene rules:

• Generated run outputs belong in .data/out/.
• Versioned evaluation inputs belong in tests/fixtures/.
• Temporary scratch roots such as deliverables/, artifacts/, tmp/, and data/ are local-only and must not be committed.

Quick Start

1) Install dependencies

python -m venv .venv
.\.venv\Scripts\pip install -r requirements.txt
.\.venv\Scripts\pip install -r requirements-dev.txt

2) Run application

.\.venv\Scripts\python -m writing_agent.launch

Default URL: http://127.0.0.1:8000

3) Run tests

python -m pytest -q tests

4) Build frontend

npm --prefix writing_agent/web/frontend_svelte run build

5) Run Node AI Gateway (incremental backend)

cd gateway/node_ai_gateway
npm install
npm test
npm start

Then set:

$env:WRITING_AGENT_LLM_BACKEND="node"
$env:WRITING_AGENT_NODE_GATEWAY_URL="http://127.0.0.1:8787"

Common Development Commands

If you have make installed:

make test
make build-frontend
make guards
make preflight

Equivalent direct commands:

python scripts/guard_file_line_limits.py --config security/file_line_limits.json --root .
python scripts/guard_function_complexity.py --config security/function_complexity_limits.json --root .
python scripts/guard_architecture_boundaries.py --config security/architecture_boundaries.json --root .
python scripts/guard_repo_hygiene.py --config security/repo_hygiene_policy.json --root .
python scripts/release_preflight.py --quick

Idempotency Cache Settings

Generation endpoints use a local file-based idempotency cache at .data/idempotency.

• WRITING_AGENT_IDEMPOTENCY_TTL_S: expiration window in seconds (default 21600)
• WRITING_AGENT_IDEMPOTENCY_MAX_ENTRIES: max cache entries to retain (default 2000)
• WRITING_AGENT_IDEMPOTENCY_SWEEP_INTERVAL_S: active cleanup interval in seconds (default 60)

Behavior:

• Lazy expiration on read (get)
• Active sweep after writes (put)
• Oldest-entry eviction when over capacity

Edit Intent Parser Settings

Edit instructions now use schema-first plan parsing with rule fallback.

• WRITING_AGENT_EDIT_PLAN_ENABLE: enable schema parser path (default 1)
• WRITING_AGENT_EDIT_PLAN_MODEL: optional dedicated parser model (default fallback to revise/default model)
• WRITING_AGENT_EDIT_PLAN_TIMEOUT_S: parser model timeout in seconds (default 20)
• WRITING_AGENT_EDIT_REQUIRE_CONFIRM_HIGH: require explicit 确认执行 for high-risk plans (default 1)
• WRITING_AGENT_EDIT_PLAN_METRICS_ENABLE: write parser/apply metrics to local file only (default 1)
• WRITING_AGENT_EDIT_PLAN_METRICS_PATH: local metrics JSONL path (default .data/metrics/edit_plan_events.jsonl)
• WRITING_AGENT_EDIT_PLAN_METRICS_MAX_BYTES: max local metrics file size before trim (default 2097152)

High-risk confirmation uses backend response fields (requires_confirmation, confirmation_reason, confirmation_action) so frontend can render explicit confirm/cancel buttons without parsing note text. Parser metrics are local silent logs only and are not exposed in user-facing UI/API.

Documentation

• Documentation index: docs/INDEX.md
• Code reading guide: docs/READING_GUIDE.md
• Getting started: docs/START_HERE.md
• Structure guide: docs/PROJECT_STRUCTURE.md
• Development guide: docs/DEVELOPMENT.md
• Operations runbook: docs/OPERATIONS_RUNBOOK.md
• Release and rollback: docs/RELEASE_AND_ROLLBACK.md
• API versioning: docs/API_VERSIONING.md
• Prompt registry: docs/PROMPT_REGISTRY.md
• RAG trust guard: docs/RAG_TRUST_GUARD.md
• Node gateway protocol: docs/NODE_AI_GATEWAY_PROTOCOL_20260227_CN.md
• Node gateway runbook: docs/NODE_AI_GATEWAY_RUNBOOK_20260227_CN.md

Community and Governance

• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Support policy: SUPPORT.md
• Changelog: CHANGELOG.md and CHANGES.md

Maintainer Tooling

• Pre-commit config: .pre-commit-config.yaml
• CODEOWNERS: .github/CODEOWNERS
• Issue templates: .github/ISSUE_TEMPLATE/
• PR template: .github/PULL_REQUEST_TEMPLATE.md
• Dependabot config: .github/dependabot.yml