guanlan 0.1.1__tar.gz

guanlan-0.1.1/.env.example

@@ -0,0 +1,15 @@
+# 观澜 / Guanlan Configuration
+# Copy to .env and fill in your values
+# Or use: guanlan configure
+
+# Exa Search (free 1000/month) — https://exa.ai
+# EXA_API_KEY=exa-your-key-here
+
+# GitHub Token (optional, for higher rate limits) — https://github.com/settings/tokens
+# GITHUB_TOKEN=ghp_your_token_here
+
+# Reddit ISP Proxy (optional, for full Reddit access)
+# REDDIT_PROXY=http://user:pass@ip:port
+
+# Groq Whisper (optional, for video transcription) — https://console.groq.com
+# GROQ_API_KEY=gsk_your_key_here

guanlan-0.1.1/.github/workflows/pytest.yml

@@ -0,0 +1,30 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and test deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -c constraints.txt -e .[dev]
+
+      - name: Run tests
+        run: |
+          pytest -q

guanlan-0.1.1/.github/workflows/release-pypi.yml

@@ -0,0 +1,223 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          twine check dist/*
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/*
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Publish to PyPI (Trusted Publisher)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  update-homebrew-tap:
+    needs: publish-pypi
+    if: ${{ needs.publish-pypi.result == 'success' }}
+    runs-on: macos-latest
+    env:
+      HOMEBREW_TAP_REPO: shenyangs/homebrew-tap
+      FORMULA_PATH: Formula/guanlan.rb
+      PACKAGE_NAME: guanlan
+      FORMULA_CLASS: Guanlan
+      PACKAGE_HOMEPAGE: https://github.com/shenyangs/Guanlan
+      PACKAGE_DESC: China-aware source and platform router for AI agents
+    steps:
+      - name: Validate required secret
+        env:
+          HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
+        run: |
+          if [ -z "${HOMEBREW_TAP_GITHUB_TOKEN}" ]; then
+            echo "Missing secret: HOMEBREW_TAP_GITHUB_TOKEN"
+            exit 1
+          fi
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+
+      - name: Generate Homebrew formula
+        env:
+          RAW_TAG: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          python -m pip install --upgrade pip
+          python -m pip install dist/*.whl
+
+          python - <<'PY'
+          import json
+          import os
+          import subprocess
+          import sys
+          import time
+          import urllib.request
+          from pathlib import Path
+
+          package_name = os.environ["PACKAGE_NAME"]
+          version = os.environ["RAW_TAG"][1:] if os.environ["RAW_TAG"].startswith("v") else os.environ["RAW_TAG"]
+          formula_path = Path(os.environ["FORMULA_PATH"])
+          formula_class = os.environ["FORMULA_CLASS"]
+          homepage = os.environ["PACKAGE_HOMEPAGE"]
+          desc = os.environ["PACKAGE_DESC"]
+
+          def normalize(name: str) -> str:
+              return name.lower().replace("_", "-")
+
+          def pick_release_file(pkg: str, ver: str) -> tuple[str, str]:
+              url = f"https://pypi.org/pypi/{pkg}/{ver}/json"
+              last_error = None
+              for _ in range(20):
+                  try:
+                      with urllib.request.urlopen(url, timeout=30) as resp:
+                          data = json.load(resp)
+                      break
+                  except Exception as err:
+                      last_error = err
+                      time.sleep(6)
+              else:
+                  raise RuntimeError(f"Failed to fetch {url}: {last_error}")
+
+              files = data.get("urls", [])
+              sdist = next((f for f in files if f.get("packagetype") == "sdist"), None)
+              if sdist:
+                  return sdist["url"], sdist["digests"]["sha256"]
+              wheel = next((f for f in files if f.get("packagetype") == "bdist_wheel"), None)
+              if wheel:
+                  return wheel["url"], wheel["digests"]["sha256"]
+              raise RuntimeError(f"No release file found for {pkg}=={ver}")
+
+          main_url, main_sha = pick_release_file(package_name, version)
+
+          freeze_output = subprocess.check_output(
+              [sys.executable, "-m", "pip", "freeze", "--exclude-editable"],
+              text=True,
+          )
+          dependencies: list[tuple[str, str]] = []
+          for line in freeze_output.splitlines():
+              if "==" not in line:
+                  continue
+              name, ver = line.split("==", 1)
+              if normalize(name) == normalize(package_name):
+                  continue
+              if normalize(name) in {"pip", "setuptools", "wheel"}:
+                  continue
+              dependencies.append((name, ver))
+
+          # De-duplicate and sort for stable formula output.
+          dedup = {(normalize(n), n, v) for n, v in dependencies}
+          sorted_deps = sorted(dedup, key=lambda item: item[0])
+
+          resources: list[str] = []
+          for _, dep_name, dep_ver in sorted_deps:
+              dep_url, dep_sha = pick_release_file(dep_name, dep_ver)
+              resources.append(
+                  "\n".join(
+                      [
+                          f'  resource "{dep_name}" do',
+                          f'    url "{dep_url}"',
+                          f'    sha256 "{dep_sha}"',
+                          "  end",
+                      ]
+                  )
+              )
+
+          resources_block = "\n\n".join(resources)
+          lines = [
+              f"class {formula_class} < Formula",
+              "  include Language::Python::Virtualenv",
+              "",
+              f'  desc "{desc}"',
+              f'  homepage "{homepage}"',
+              f'  url "{main_url}"',
+              f'  sha256 "{main_sha}"',
+              '  license "MIT"',
+          ]
+
+          if resources_block:
+              lines.append("")
+              lines.extend(resources_block.splitlines())
+
+          lines.extend(
+              [
+                  "",
+                  '  depends_on "python@3.12"',
+                  "",
+                  "  def install",
+                  "    virtualenv_install_with_resources",
+                  "  end",
+                  "",
+                  "  test do",
+                  '    output = shell_output("#{bin}/guanlan --version")',
+                  "    assert_match version.to_s, output",
+                  "  end",
+                  "end",
+              ]
+          )
+          formula = "\n".join(lines)
+
+          formula_path.parent.mkdir(parents=True, exist_ok=True)
+          formula_path.write_text(formula + "\n", encoding="utf-8")
+          PY
+
+      - name: Push formula to tap
+        env:
+          HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          git clone "https://x-access-token:${HOMEBREW_TAP_GITHUB_TOKEN}@github.com/${HOMEBREW_TAP_REPO}.git" tap
+          mkdir -p "tap/$(dirname "${FORMULA_PATH}")"
+          cp "${FORMULA_PATH}" "tap/${FORMULA_PATH}"
+
+          cd tap
+          if git diff --quiet -- "${FORMULA_PATH}"; then
+            echo "No formula changes detected."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add "${FORMULA_PATH}"
+          git commit -m "guanlan ${GITHUB_REF_NAME#v}"
+          git push

guanlan-0.1.1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+.claude/
+.env
+.guanlan/
+*.log

guanlan-0.1.1/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+This repository is designed as a CLI-first search productivity tool for AI agents.
+
+When using Guanlan as an agent, prefer this minimal command set:
+
+```bash
+guanlan search "query" --limit 8
+guanlan search "中文问题" --profile china --limit 8
+guanlan search "政策或产业问题" --profile china --scope party_central
+guanlan search "电商零售问题" --profile china --scope ecommerce
+guanlan search --list-scopes
+guanlan read "https://example.com/article" --max-chars 12000
+guanlan hotnews baidu --limit 10
+guanlan hotnews v2ex --limit 10
+guanlan doctor --trace
+```
+
+Read [docs/agent-usage.md](docs/agent-usage.md) for the full agent routing guide.
+
+Safety rules:
+
+- Do not read browser cookies unless the user explicitly asks.
+- Do not run `guanlan configure --from-browser ...` without user approval.
+- Do not run `guanlan doctor --auth-check` unless the user wants deep auth checks.
+- Do not post, comment, like, follow, or send messages automatically.
+- Prefer public search/read/hotnews first, then ask for authorization only when needed.

guanlan-0.1.1/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog / 更新日志
+
+All notable changes to Guanlan will be documented in this file.
+
+观澜版本的重要变更从此处开始记录。
+
+---
+
+## [0.1.0] - 2026-05-01
+
+### Added / 新增
+
+- Established the Guanlan project baseline, package identity, and documentation set.
+- Added a China-aware agent workflow centered on `guanlan search`, `guanlan read`, and `guanlan hotnews`.
+- Added scoped source routing for `party_central`, `gov`, `local_official`, `business`, `ecommerce`, `tech_dev`, `finance`, and `social_web`.
+- Added native hotnews aggregation and normalized Markdown output for Chinese trend tracking.
+
+### Changed / 变更
+
+- Standardized the CLI, package, config directory, and docs around the `guanlan` identity.
+- Clarified safety defaults: public read-only access first, explicit approval for cookies, Keychain access, and deep auth checks.
+- Reorganized install, troubleshooting, agent-usage, and source-attribution docs to reflect Guanlan's own positioning.

guanlan-0.1.1/CLAUDE.md

@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+## Project
+观澜 / Guanlan — Python CLI + library for AI-agent search, reading, hotnews, and source routing across the Chinese web.
+Positioning: CLI-first, read-first router with explicit authorization boundaries.
+Repo: local workspace, public remote not configured yet | License: MIT | Version: 0.1.0
+
+## Commands
+- `pip install -e .` — Dev install
+- `pytest tests/ -v` — All tests
+- `pytest tests/test_cli.py -v` — CLI tests only
+- `bash test.sh` — Full integration test (creates venv, installs, runs doctor + channel tests)
+- `python -m guanlan.cli doctor` — Run diagnostics
+- `python -m guanlan.cli install --env=auto` — Auto-configure
+
+## Structure
+- `guanlan/cli.py` — CLI entry point (argparse)
+- `guanlan/core.py` — Core read/search routing logic
+- `guanlan/config.py` — Config management (YAML, env vars)
+- `guanlan/doctor.py` — Diagnostics engine
+- `guanlan/channels/` — One file per platform (twitter.py, reddit.py, youtube.py, etc.)
+- `guanlan/channels/base.py` — Base channel class (all channels inherit from this)
+- `guanlan/integrations/mcp_server.py` — MCP server integration
+- `guanlan/skill/` — OpenClaw skill files
+- `guanlan/guides/` — Usage guides
+- `tests/` — pytest tests
+- `config/mcporter.json` — MCP tool config
+
+## Conventions
+- Python 3.10+ with type hints
+- Each channel is a single file in `channels/`, inherits from `BaseChannel`
+- Channel contract: must implement `can_handle(url)`, `read(url)`, `search(query)`, `check()` methods
+- Use `loguru` for logging, `rich` for CLI output
+- Commit format: `type(scope): message` (one commit = one thing)
+- All upstream tool calls go through public API/CLI, never hack internals
+
+## Rules
+- NEVER modify upstream open source projects' source code
+- 观澜 / Guanlan keeps platform access modular: route, read, diagnose, and degrade cleanly.
+- Version in THREE places must match: `pyproject.toml`, `__init__.py`, `tests/test_cli.py`
+- Always new branch for changes, PR to main, never push to main directly
+- Run `pytest tests/ -v` before committing — all tests must pass
+- Cookie-based auth (Twitter, XHS): use Cookie-Editor export method only, no QR scan
+- XHS login: Cookie-Editor browser export only (QR will hang)

guanlan-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,107 @@
+# Contributing to 观澜 / Guanlan
+
+Thank you for your interest in contributing to 观澜 / Guanlan! This document provides guidelines and instructions for contributing.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally
+3. Create a new branch for your contribution
+4. Make your changes
+5. Run tests and linting
+6. Submit a pull request
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/Guanlan.git
+cd Guanlan
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Install pre-commit hooks (optional but recommended)
+pre-commit install
+```
+
+## Code Style
+
+We use the following tools to maintain code quality:
+
+- **ruff**: Linting and import sorting
+- **mypy**: Type checking
+- **pytest**: Testing
+
+Run all checks before submitting a PR:
+
+```bash
+# Linting
+ruff check guanlan tests
+ruff format guanlan tests
+
+# Type checking
+mypy guanlan
+
+# Tests
+pytest
+```
+
+## Adding New Channels
+
+观澜 / Guanlan uses a unified channel interface. To add a new platform:
+
+1. Create a new file in `guanlan/channels/`
+2. Implement the channel contract (see existing channels for examples)
+3. Add tests in `tests/test_channels.py`
+4. Update `guanlan/doctor.py` to include the new channel
+5. Update documentation
+
+## Pull Request Guidelines
+
+- **Small, focused changes** are preferred over large refactors
+- Include tests for new functionality
+- Update documentation if needed
+- Follow existing code style
+- Reference any related issues
+
+## Reporting Issues
+
+When reporting bugs, please include:
+
+- Python version
+- Operating system
+- Steps to reproduce
+- Expected vs actual behavior
+- Any error messages
+
+## Questions?
+
+Feel free to open an issue for questions or join discussions.
+
+---
+
+感谢您对 观澜 / Guanlan 的贡献！本文档提供了贡献指南。
+
+## 快速开始
+
+1. 在 GitHub 上 fork 仓库
+2. 本地 clone 您的 fork
+3. 创建新分支
+4. 提交更改
+5. 运行测试和 lint
+6. 提交 pull request
+
+## 代码规范
+
+- 使用 **ruff** 进行代码检查
+- 使用 **mypy** 进行类型检查
+- 使用 **pytest** 运行测试
+
+## 添加新渠道
+
+1. 在 `guanlan/channels/` 创建新文件
+2. 实现渠道接口
+3. 添加测试
+4. 更新 doctor 检测
+5. 更新文档

guanlan-0.1.1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Guanlan Team
+Copyright (c) 2025 Agent Eyes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

guanlan-0.1.1/NOTICE

@@ -0,0 +1,27 @@
+Guanlan Third-Party Notices
+===========================
+
+Guanlan is released under the MIT License.
+
+Copyright (c) 2026 Guanlan Team
+
+Portions of Guanlan reference or adapt ideas and implementation patterns from
+the following MIT-licensed open-source projects:
+
+Agent-Reach
+-----------
+
+Copyright (c) 2025 Agent Eyes
+License: MIT License
+Source: https://github.com/Panniantong/Agent-Reach
+License text: https://github.com/Panniantong/Agent-Reach/blob/main/LICENSE
+
+NewsNow
+-------
+
+Copyright (c) 2024 ourongxing
+License: MIT License
+Source: https://github.com/ourongxing/newsnow
+License text: https://github.com/ourongxing/newsnow/blob/main/LICENSE
+
+See docs/SOURCE_ATTRIBUTION.md for the project-level source attribution notes.