deepseek-automation

name	deepseek-automation
description	Use when implementing, resuming, reviewing, or verifying the DeepSeek++ Codex-style automation feature in this repository. Covers reading docs/progress/MASTER.md, following GitHub Issues

DeepSeek Automation

Use this project-local skill for the DeepSeek++ automation implementation. The feature goal is: create Codex-style automations that can run immediately in a new DeepSeek chat session and then continue in that same automation session on a cron/RRULE-like schedule.

Start Every Session

1. Read docs/progress/MASTER.md.
2. Confirm tracking mode. Current mode is GITHUB_STANDARD.
3. Query GitHub before starting work:

gh issue list -R zhu1090093659/deepseek-pp --label "spec-driven" --state open --json number,title,labels,milestone

4. Pick the next open issue in dependency order unless the user names a task.
5. Read the selected Issue body and linked local docs under docs/analysis/ and docs/plan/.
6. Update docs/progress/MASTER.md Current Status at session start and end.

Architecture Rules

• Keep scheduling in background code.
• Keep actual DeepSeek request execution in the DeepSeek page main-world context.
• Use content script only as a narrow bridge between background and main world.
• Do not add automation business logic directly into fetch-hook.ts unless the task is explicitly about hook compatibility.
• Prefer new focused files under core/automation/.
• Do not rely on background-only fetch('/api/v0/chat/completion') for MVP; DeepSeek web completion has challenge/proof-of-work behavior.
• Preserve existing memory, skill, preset, and tool-call behavior unless the Issue explicitly changes it.

DeepSeek Web Facts

Verified on 2026-05-21:

• Completion endpoint: /api/v0/chat/completion.
• History endpoint: /api/v0/chat/history_messages.
• Completion request fields include chat_session_id, parent_message_id, model_type, prompt, ref_file_ids, thinking_enabled, search_enabled, action, and preempt.
• New session and same-session continuation work from the web UI.
• Reload restores the automation test session from history.
• Persist the latest valid parent message id after every run and reconcile it against history.

S.U.P.E.R Principles

S - Single Purpose

From Unix philosophy.

• Each module, file, and function solves exactly one problem
• Prefer decomposition; power comes from composition
• One skill does one thing, one worker does one thing, one script does one thing

Litmus test: if you cannot describe a module's responsibility in a single sentence, it needs to be split.

Anti-pattern: a script that fetches data, computes metrics, renders charts, and sends notifications.

Correct approach:

fetch_data.py  -> data retrieval only, outputs JSON
compute.py     -> computation only, reads JSON writes JSON
render.py      -> rendering only, reads JSON generates HTML
notify.py      -> notification only, reads JSON calls webhook

U - Unidirectional Flow

From Clean Architecture.

• Data always flows in one direction: input -> processing -> output
• Dependencies always point inward: outer layers depend on inner layers, inner layers know nothing about outer layers
• No reverse dependencies, no circular calls

Layered model:

+-------------------------------+
|  Infrastructure (API, DB, UI) |  <- outermost, replaceable at will
+-------------------------------+
|  Adapters (transform, format) |
+-------------------------------+
|  Core business (pure logic)   |  <- innermost, zero external deps
+-------------------------------+

Litmus test: can the core logic run unit tests with zero external services? If not, the dependency direction is wrong.

P - Ports over Implementation

From Hexagonal Architecture.

• Define interface contracts (data structures, JSON Schema) before writing implementation
• Use intermediate formats (JSON files, standard data structures) to isolate upstream from downstream
• Swapping a data source, a rendering layer, or a notification channel requires zero changes to core logic

Practices:

1. Every module's input and output must be a serializable data structure
2. Module boundaries communicate via JSON files or standard data structures; in-process typed objects are fine, but cross-module interfaces must be serializable
3. Define explicit schemas - not "just read the code to figure out the format"

E - Environment-Agnostic

From 12-Factor App.

• Configuration injected via environment variables or config files, never hardcoded
• All dependencies explicitly declared (requirements.txt / package.json), no implicit reliance on global system packages
• Processes are stateless; all persistence delegated to external storage
• Logs go to stdout, not to files
• Same codebase runs on local machine, Cloudflare Workers, VPS, Docker

Configuration precedence:

Environment variables > .env file > config.json > in-code defaults

Checklist:

• All API keys and webhook URLs read from environment variables?
• All dependencies explicitly declared in a dependency file?
• No hardcoded file path assumptions?
• Can a different machine run this code with zero modifications?

R - Replaceable Parts

The natural consequence and ultimate goal of S + U + P + E.

• Any layer can be replaced without affecting others
• Replacement cost is the core metric of architecture quality
• If replacing one component triggers cascading changes in unrelated modules, the architecture is broken

Replacement matrix:

Replacing	Impact scope	Correct approach
Data source API	Adapter layer only	Write new fetcher, output same JSON
Frontend renderer	Render layer only	Read same JSON, swap render implementation
Notification channel	Notification layer	Swap webhook adapter
Deployment platform	Deploy config only	Change wrangler.toml or Dockerfile
Programming language	Implementation only	JSON contracts unchanged, rewrite in any language

S.U.P.E.R Code Review Checklist

Run this before marking any task done.

1. The touched files each have one clear responsibility.
2. New automation logic is not dumped into fetch-hook.ts, content.ts, or background.ts when a focused module would do.
3. Data flows sidepanel/alarm -> background -> content -> main-world -> result without circular imports.
4. Cross-boundary messages have explicit TypeScript contracts.
5. Persisted objects are serializable and migration-friendly.
6. DeepSeek-specific behavior is isolated behind runner/history helpers.
7. Chrome-specific behavior is isolated behind background/tab orchestration helpers.
8. Errors are structured enough for run history and UI display.
9. The implementation can be tested or type-checked without a live DeepSeek page where possible.
10. npm run compile passes, or the blocking reason is recorded.

Scoring rule: all pass = proceed; 1-2 fail = fix first; 3+ fail = stop and refactor.

Phase Guidance

• Phase 1: implement contracts, store, and schedule calculation first.
• Phase 2: add scheduler and bridge; keep the main-world runner isolated.
• Phase 3: add Automation UI after store contracts are stable.
• Phase 4: add tab/login failure handling, timeouts, retry/missed-run policy, and prompt injection compatibility.
• Phase 5: verify live DeepSeek behavior and document limitations.

Progress and Telemetry

For every completed Issue:

1. Comment on the GitHub Issue with actual effort, S.U.P.E.R score, unplanned dependency count, files changed, and verification.
2. Update docs/progress/MASTER.md Current Status and phase counts if needed.
3. If a drift threshold in the milestone description is reached, stop and replan before continuing.

Archive Trigger

When all GitHub Issues are closed and all milestones are complete, enter archive mode:

1. Move docs/analysis/, docs/plan/, and docs/progress/ into docs/archives/deepseek-automation/.
2. Move this skill to docs/archives/deepseek-automation/skill/SKILL.md.
3. Update docs/archives/README.md.
4. Close milestones if they are still open.