Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
157 lines (107 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

157 lines (107 loc) · 10.7 KB
Raw

Contributing to FlyBot

Thank you for helping. This file explains how to set up the plugin, how to test a change and which rules a change must follow. For what the plugin does and how users install it, see README.md.

Pull requests

ThinkFlowLab/FlyBot accepts pull requests for FlyBot plugin and docs work when they follow this file, AGENTS.md, LESSONS.md, and docs/code-standards.md. Prefer small PRs: one issue or one tightly coupled fix per branch.

Upstream DS Bot (Fei2411/DeepSeek-Bot) may still decline external PRs while that tree moves quickly—open an issue there (see Report a problem) or use Discussions for product questions. Do not assume a FlyBot PR is automatically upstreamed.

Security reports: use the repository Security tab, not a public PR description with exploit detail.

Maintainer / agent loop

A person talks to the Chief (the Main Bot); the Chief hands work to Triage, Dev and Reviewer, each a Bot in the same tree. OpenCode and Codex are gone (owner decision 2026-10-22).

The rules that decide whether a change may merge — tiers and the PASS, the enqueue guard, the merge queue, one conclusion per tip — live in AGENTS.md and AGENTS.md → Merge gates. This section says only who does what, so the two files cannot drift apart:

  1. Read LESSONS.md and docs/code-standards.md before coding.
  2. Dev implements on a branch proven against the live origin/main (AGENTS.md step 2): a test that fails without the change comes first.
  3. Reviewer writes the conclusion at the tip with review-pr; the implementer never writes it. T2/T3 need that PASS, T0/T1 need none, and neither replaces green CI.
  4. The Bot that gated the pull request enqueues it (AGENTS.md → Merge gates); no human approve is read.
  5. One worktree / session per issue. Security follow-ups from PR #2 first when open: issues #9 → #10 → #8. Promote a lesson into code-standards after ≥3 days when it stays true.

Verifier checklist (every agent or maintainer status report)

  • Tip SHA named (git rev-parse HEAD)
  • Commands run at that tip listed with pass/fail
  • Material checks not run listed (smoke / Desktop / real model / …)
  • New regression fails without the fix, then passes with it (when adding tests)
  • Fix covers the class (shared fence helper, sanitization), not only one sample
  • T2/T3: a PASS at the same tip (self-PASS counts) before merge / “open PR”; T0/T1 need none
  • npm test, node scripts/build-client.mjs --check, npm run lint green for code changes (or honestly waived)

The rules that matter most

  1. Build on DSH; never patch it. The Bot features are a DSH plugin: use the plugin APIs that DSH documents (Cordis services, the plugin client entry, profile patches). The desktop app starts DSH only through the entry points that DSH documents (@deepseek-ai/dsh/profile-boot, the dsh command). Do not patch DeepSeek Harness, and do not depend on files inside a DSH install. When a feature needs something that DSH does not offer, open an issue here first; the fix can belong in DSH.
  2. Every Bot is a DSH Session. Bot work runs through the normal DSH agent loop, tools and model routes. Do not add a second agent runtime.
  3. No real secrets anywhere. Do not commit API keys, tokens, cookies, DSH_HOME folders, logs or screenshots with personal data. The tests and the test bench use a scripted mock model and need no key.
  4. Only original material. Do not copy code, text, icons, logos or other graphics from other products or websites. Code under a license compatible with Apache 2.0 is the only exception: say where it comes from and add its notice to a NOTICE file.
  5. Every change is tested. Run the unit tests and the client check for every change (see Test a change).

Set up

You need:

  • Node.js 22.19 or later (or 24 and later).
  • Git.
  • For the test bench only: pnpm 11 and a checkout of DeepSeek Harness at the DSH version that the plugin is tested with.
git clone https://github.com/ThinkFlowLab/FlyBot.git ds-bot-repo
cd ds-bot-repo/core

# The plugin's own build tool (esbuild only).
npm ci

# The DSH packages that the unit tests and the linter load, from npm, into dev/harness/.
npm run harness

For the test bench, add the DeepSeek Harness checkout next to the plugin folder (this folder is ignored by Git):

cd ..
git clone https://github.com/deepseek-ai/deepseek-harness.git
git -C deepseek-harness checkout dsh-v0.2.0-rc.2
(cd deepseek-harness && pnpm install)

If your DeepSeek Harness checkout is somewhere else, set DSH_HARNESS to its path. DSH_HARNESS also takes the place of dev/harness/ for the unit tests and the linter.

The @deepseek-ai/* packages are peer dependencies: in a real install, the DSH profile supplies them. core/.npmrc keeps npm from installing them into the plugin folder.

Layout

Path What it is
core/index.js, core/src/host/ The server side: Bot roster and store, tools, turns and delivery, group chats, conversation parts and the search index, images, the Bot browser bridge, the api/bot channel
core/src/client/ The browser side: sidebar, chat, panels and dialogs, themes, characters, the Bot browser panel
core/client.js Generated from src/client/ by scripts/build-client.mjs. It is committed, so that Git installs need no build step
core/web-search.js The auto web-search provider. It does not depend on the Bot team code
core/cordis.patch.yml The profile patch that the plugin brings
core/test/ Unit tests and fixtures
core/dev/ The DSH packages for the unit tests (harness/), the mock model, the test bench, the smoke test, the character generator, the Desktop scripts for Linux, and two tools for real models: the steward evaluation and a logging pass-through

Test a change

Run these in core/:

npm run build                          # src/client → client.js
npm test                               # unit tests; they also fail if client.js is stale
node scripts/build-client.mjs --check  # client.js matches src/client
npm run lint                           # oxlint

CI runs the same three checks on every pull request, on Linux and Windows.

For a change to the server side (index.js, src/host/), also run the smoke test. It starts the mock model and a DSH Web with the plugin linked from your checkout, and walks through the main flows (Bots, group chats, conversation parts, condensing, settings). CONTEXT_WINDOW and CHECK_RATIO give the mock models a small window, so a few long replies reach the check line:

CONTEXT_WINDOW=100000 CHECK_RATIO=0.45 dev/bench.sh smoke 3096 8796 reset && node dev/smoke.mjs smoke 3096
dev/bench.sh smoke 3096 8796 stop

To try the plugin by hand, start a bench and open the address that it prints:

dev/bench.sh dev 3081 8771 reset    # mock model + DSH Web; data in ../.dsh-test-dev

The mock model answers a fixed set of commands, so a bench costs no tokens. The commands are listed at the top of dev/mock-llm.mjs. Bench data stays in .dsh-test-<name>/ next to the plugin folder and never touches your own ~/.dsh.

For a change to the context steward or its prompts (src/host/steward.js), also check it on a real model. dev/steward-eval.mjs runs its decisions on fixed conversation endings, and dev/llm-tap.mjs logs every call a real bench makes. Both cost tokens and explain their use at the top.

For a change to the Bot browser, check it in DSH Desktop. On Linux, the scripts in dev/desktop-linux/ run DSH Desktop under Xvfb; each script explains its use at the top.

Write a change

  • Keep a change to one subject.
  • Do not edit client.js by hand. Change src/client/, run npm run build and commit both.
  • Follow the style of the code around your change. Write a comment only when the reason for the code is not clear from the code itself.
  • Write commit messages in English. Use a short subject in the imperative mood ("Keep group replies visible") and explain the reason in the body.
  • For a change that users can see, add one file changelog.d/<issue-or-slug>.<kind>.md (kind: added, changed, fixed, ...; see changelog.d/README.md). Do not edit CHANGELOG.md in a feature PR: the release assembles the fragments, and one file per change means two PRs never conflict there.

Report a problem

The easiest way is from FlyBot itself: open Settings → Feedback, write what happened and select Report on GitHub. It opens a new issue with the core (ds-bot) and DSH versions, your system, the models and the recent errors already filled in. Copy puts the same text on the clipboard, and Download saves the full error log (<DSH_HOME>/bot/logs/diagnostics.jsonl). Report on GitHub opens the issue form of ThinkFlowLab/FlyBot. A problem that is only in the upstream DS Bot core can still be reported to its repository (Fei2411/DeepSeek-Bot).

If you open an issue by hand, include:

  • The DSH version (DSH Desktop or @deepseek-ai/dsh), your operating system, and whether you use DSH Desktop or DSH Web.
  • How you installed FlyBot (npm, release file, Git address or command line) and its version.
  • What you did, what you expected and what happened, with the exact error text.
  • A screenshot of the whole window, with the chat and the error.
  • The steps that make it happen again.

FlyBot removes API keys, tokens, saved secrets and your home folder from its diagnostics. Read the text before you post it, and remove personal data from screenshots.

For a security problem, do not open a public issue. Use Report a vulnerability on the repository's Security tab.

Issues are for bug reports. Questions, ideas and feature requests belong in Discussions.

Agent docs map

Doc Role
AGENTS.md Hard DSH rules + Magpie-style iteration loop
LESSONS.md Dated lessons (Seen N×); promote after ≥3 days
docs/code-standards.md Verifier honesty, fences, merge-only-reviewed-tip
.claude/skills/review-pr/SKILL.md PASS / FAIL / INC review report shape

License

FlyBot is licensed under the Apache License 2.0. When you submit a contribution, you agree that it is licensed under the same license, as section 5 of the license says.